local-lib5/lib/perl5/IO/Compress/Bzip2.pm

   1 package IO::Compress::Bzip2 ;
   2
   3 use strict ;
   4 use warnings;
   5 use bytes;
   6 require Exporter ;
   7
   8 use IO::Compress::Base 2.023 ;
   9
  10 use IO::Compress::Base::Common  2.023 qw(createSelfTiedObject);
  11 use IO::Compress::Adapter::Bzip2 2.023 ;
  12
  13
  14
  15 our ($VERSION, @ISA, @EXPORT_OK, %EXPORT_TAGS, $Bzip2Error);
  16
  17 $VERSION = '2.023';
  18 $Bzip2Error = '';
  19
  20 @ISA    = qw(Exporter IO::Compress::Base);
  21 @EXPORT_OK = qw( $Bzip2Error bzip2 ) ;
  22 %EXPORT_TAGS = %IO::Compress::Base::EXPORT_TAGS ;
  23 push @{ $EXPORT_TAGS{all} }, @EXPORT_OK ;
  24 Exporter::export_ok_tags('all');
  25
  26
  27
  28 sub new
  29 {
  30     my $class = shift ;
  31
  32     my $obj = createSelfTiedObject($class, \$Bzip2Error);
  33     return $obj->_create(undef, @_);
  34 }
  35
  36 sub bzip2
  37 {
  38     my $obj = createSelfTiedObject(undef, \$Bzip2Error);
  39     $obj->_def(@_);
  40 }
  41
  42
  43 sub mkHeader
  44 {
  45     my $self = shift ;
  46     return '';
  47
  48 }
  49
  50 sub getExtraParams
  51 {
  52     my $self = shift ;
  53
  54     use IO::Compress::Base::Common  2.023 qw(:Parse);
  55
  56     return (
  57             'BlockSize100K' => [0, 1, Parse_unsigned,  1],
  58             'WorkFactor'    => [0, 1, Parse_unsigned,  0],
  59             'Verbosity'     => [0, 1, Parse_boolean,   0],
  60         );
  61 }
  62
  63
  64
  65 sub ckParams
  66 {
  67     my $self = shift ;
  68     my $got = shift;
  69
  70     # check that BlockSize100K is a number between 1 & 9
  71     if ($got->parsed('BlockSize100K')) {
  72         my $value = $got->value('BlockSize100K');
  73         return $self->saveErrorString(undef, "Parameter 'BlockSize100K' not between 1 and 9, got $value")
  74             unless defined $value && $value >= 1 && $value <= 9;
  75
  76     }
  77
  78     # check that WorkFactor between 0 & 250
  79     if ($got->parsed('WorkFactor')) {
  80         my $value = $got->value('WorkFactor');
  81         return $self->saveErrorString(undef, "Parameter 'WorkFactor' not between 0 and 250, got $value")
  82             unless $value >= 0 && $value <= 250;
  83     }
  84
  85     return 1 ;
  86 }
  87
  88
  89 sub mkComp
  90 {
  91     my $self = shift ;
  92     my $got = shift ;
  93
  94     my $BlockSize100K = $got->value('BlockSize100K');
  95     my $WorkFactor    = $got->value('WorkFactor');
  96     my $Verbosity     = $got->value('Verbosity');
  97
  98     my ($obj, $errstr, $errno) = IO::Compress::Adapter::Bzip2::mkCompObject(
  99                                                $BlockSize100K, $WorkFactor,
 100                                                $Verbosity);
 101
 102     return $self->saveErrorString(undef, $errstr, $errno)
 103         if ! defined $obj;
 104
 105     return $obj;
 106 }
 107
 108
 109 sub mkTrailer
 110 {
 111     my $self = shift ;
 112     return '';
 113 }
 114
 115 sub mkFinalTrailer
 116 {
 117     return '';
 118 }
 119
 120 #sub newHeader
 121 #{
 122 #    my $self = shift ;
 123 #    return '';
 124 #}
 125
 126 sub getInverseClass
 127 {
 128     return ('IO::Uncompress::Bunzip2');
 129 }
 130
 131 sub getFileInfo
 132 {
 133     my $self = shift ;
 134     my $params = shift;
 135     my $file = shift ;
 136
 137 }
 138
 139 1;
 140
 141 __END__
 142
 143 =head1 NAME
 144
 145 IO::Compress::Bzip2 - Write bzip2 files/buffers
 146
 147
 148
 149 =head1 SYNOPSIS
 150
 151     use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
 152
 153     my $status = bzip2 $input => $output [,OPTS]
 154         or die "bzip2 failed: $Bzip2Error\n";
 155
 156     my $z = new IO::Compress::Bzip2 $output [,OPTS]
 157         or die "bzip2 failed: $Bzip2Error\n";
 158
 159     $z->print($string);
 160     $z->printf($format, $string);
 161     $z->write($string);
 162     $z->syswrite($string [, $length, $offset]);
 163     $z->flush();
 164     $z->tell();
 165     $z->eof();
 166     $z->seek($position, $whence);
 167     $z->binmode();
 168     $z->fileno();
 169     $z->opened();
 170     $z->autoflush();
 171     $z->input_line_number();
 172     $z->newStream( [OPTS] );
 173
 174     $z->close() ;
 175
 176     $Bzip2Error ;
 177
 178     # IO::File mode
 179
 180     print $z $string;
 181     printf $z $format, $string;
 182     tell $z
 183     eof $z
 184     seek $z, $position, $whence
 185     binmode $z
 186     fileno $z
 187     close $z ;
 188
 189
 190 =head1 DESCRIPTION
 191
 192 This module provides a Perl interface that allows writing bzip2
 193 compressed data to files or buffer.
 194
 195 For reading bzip2 files/buffers, see the companion module
 196 L<IO::Uncompress::Bunzip2|IO::Uncompress::Bunzip2>.
 197
 198 =head1 Functional Interface
 199
 200 A top-level function, C<bzip2>, is provided to carry out
 201 "one-shot" compression between buffers and/or files. For finer
 202 control over the compression process, see the L</"OO Interface">
 203 section.
 204
 205     use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
 206
 207     bzip2 $input => $output [,OPTS]
 208         or die "bzip2 failed: $Bzip2Error\n";
 209
 210 The functional interface needs Perl5.005 or better.
 211
 212 =head2 bzip2 $input => $output [, OPTS]
 213
 214 C<bzip2> expects at least two parameters, C<$input> and C<$output>.
 215
 216 =head3 The C<$input> parameter
 217
 218 The parameter, C<$input>, is used to define the source of
 219 the uncompressed data.
 220
 221 It can take one of the following forms:
 222
 223 =over 5
 224
 225 =item A filename
 226
 227 If the C<$input> parameter is a simple scalar, it is assumed to be a
 228 filename. This file will be opened for reading and the input data
 229 will be read from it.
 230
 231 =item A filehandle
 232
 233 If the C<$input> parameter is a filehandle, the input data will be
 234 read from it.
 235 The string '-' can be used as an alias for standard input.
 236
 237 =item A scalar reference
 238
 239 If C<$input> is a scalar reference, the input data will be read
 240 from C<$$input>.
 241
 242 =item An array reference
 243
 244 If C<$input> is an array reference, each element in the array must be a
 245 filename.
 246
 247 The input data will be read from each file in turn.
 248
 249 The complete array will be walked to ensure that it only
 250 contains valid filenames before any data is compressed.
 251
 252 =item An Input FileGlob string
 253
 254 If C<$input> is a string that is delimited by the characters "<" and ">"
 255 C<bzip2> will assume that it is an I<input fileglob string>. The
 256 input is the list of files that match the fileglob.
 257
 258 If the fileglob does not match any files ...
 259
 260 See L<File::GlobMapper|File::GlobMapper> for more details.
 261
 262 =back
 263
 264 If the C<$input> parameter is any other type, C<undef> will be returned.
 265
 266 =head3 The C<$output> parameter
 267
 268 The parameter C<$output> is used to control the destination of the
 269 compressed data. This parameter can take one of these forms.
 270
 271 =over 5
 272
 273 =item A filename
 274
 275 If the C<$output> parameter is a simple scalar, it is assumed to be a
 276 filename.  This file will be opened for writing and the compressed
 277 data will be written to it.
 278
 279 =item A filehandle
 280
 281 If the C<$output> parameter is a filehandle, the compressed data
 282 will be written to it.
 283 The string '-' can be used as an alias for standard output.
 284
 285 =item A scalar reference
 286
 287 If C<$output> is a scalar reference, the compressed data will be
 288 stored in C<$$output>.
 289
 290 =item An Array Reference
 291
 292 If C<$output> is an array reference, the compressed data will be
 293 pushed onto the array.
 294
 295 =item An Output FileGlob
 296
 297 If C<$output> is a string that is delimited by the characters "<" and ">"
 298 C<bzip2> will assume that it is an I<output fileglob string>. The
 299 output is the list of files that match the fileglob.
 300
 301 When C<$output> is an fileglob string, C<$input> must also be a fileglob
 302 string. Anything else is an error.
 303
 304 =back
 305
 306 If the C<$output> parameter is any other type, C<undef> will be returned.
 307
 308 =head2 Notes
 309
 310 When C<$input> maps to multiple files/buffers and C<$output> is a single
 311 file/buffer the input files/buffers will be stored
 312 in C<$output> as a concatenated series of compressed data streams.
 313
 314 =head2 Optional Parameters
 315
 316 Unless specified below, the optional parameters for C<bzip2>,
 317 C<OPTS>, are the same as those used with the OO interface defined in the
 318 L</"Constructor Options"> section below.
 319
 320 =over 5
 321
 322 =item C<< AutoClose => 0|1 >>
 323
 324 This option applies to any input or output data streams to
 325 C<bzip2> that are filehandles.
 326
 327 If C<AutoClose> is specified, and the value is true, it will result in all
 328 input and/or output filehandles being closed once C<bzip2> has
 329 completed.
 330
 331 This parameter defaults to 0.
 332
 333 =item C<< BinModeIn => 0|1 >>
 334
 335 When reading from a file or filehandle, set C<binmode> before reading.
 336
 337 Defaults to 0.
 338
 339 =item C<< Append => 0|1 >>
 340
 341 TODO
 342
 343 =back
 344
 345 =head2 Examples
 346
 347 To read the contents of the file C<file1.txt> and write the compressed
 348 data to the file C<file1.txt.bz2>.
 349
 350     use strict ;
 351     use warnings ;
 352     use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
 353
 354     my $input = "file1.txt";
 355     bzip2 $input => "$input.bz2"
 356         or die "bzip2 failed: $Bzip2Error\n";
 357
 358 To read from an existing Perl filehandle, C<$input>, and write the
 359 compressed data to a buffer, C<$buffer>.
 360
 361     use strict ;
 362     use warnings ;
 363     use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
 364     use IO::File ;
 365
 366     my $input = new IO::File "<file1.txt"
 367         or die "Cannot open 'file1.txt': $!\n" ;
 368     my $buffer ;
 369     bzip2 $input => \$buffer
 370         or die "bzip2 failed: $Bzip2Error\n";
 371
 372 To compress all files in the directory "/my/home" that match "*.txt"
 373 and store the compressed data in the same directory
 374
 375     use strict ;
 376     use warnings ;
 377     use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
 378
 379     bzip2 '</my/home/*.txt>' => '<*.bz2>'
 380         or die "bzip2 failed: $Bzip2Error\n";
 381
 382 and if you want to compress each file one at a time, this will do the trick
 383
 384     use strict ;
 385     use warnings ;
 386     use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
 387
 388     for my $input ( glob "/my/home/*.txt" )
 389     {
 390         my $output = "$input.bz2" ;
 391         bzip2 $input => $output
 392             or die "Error compressing '$input': $Bzip2Error\n";
 393     }
 394
 395 =head1 OO Interface
 396
 397 =head2 Constructor
 398
 399 The format of the constructor for C<IO::Compress::Bzip2> is shown below
 400
 401     my $z = new IO::Compress::Bzip2 $output [,OPTS]
 402         or die "IO::Compress::Bzip2 failed: $Bzip2Error\n";
 403
 404 It returns an C<IO::Compress::Bzip2> object on success and undef on failure.
 405 The variable C<$Bzip2Error> will contain an error message on failure.
 406
 407 If you are running Perl 5.005 or better the object, C<$z>, returned from
 408 IO::Compress::Bzip2 can be used exactly like an L<IO::File|IO::File> filehandle.
 409 This means that all normal output file operations can be carried out
 410 with C<$z>.
 411 For example, to write to a compressed file/buffer you can use either of
 412 these forms
 413
 414     $z->print("hello world\n");
 415     print $z "hello world\n";
 416
 417 The mandatory parameter C<$output> is used to control the destination
 418 of the compressed data. This parameter can take one of these forms.
 419
 420 =over 5
 421
 422 =item A filename
 423
 424 If the C<$output> parameter is a simple scalar, it is assumed to be a
 425 filename. This file will be opened for writing and the compressed data
 426 will be written to it.
 427
 428 =item A filehandle
 429
 430 If the C<$output> parameter is a filehandle, the compressed data will be
 431 written to it.
 432 The string '-' can be used as an alias for standard output.
 433
 434 =item A scalar reference
 435
 436 If C<$output> is a scalar reference, the compressed data will be stored
 437 in C<$$output>.
 438
 439 =back
 440
 441 If the C<$output> parameter is any other type, C<IO::Compress::Bzip2>::new will
 442 return undef.
 443
 444 =head2 Constructor Options
 445
 446 C<OPTS> is any combination of the following options:
 447
 448 =over 5
 449
 450 =item C<< AutoClose => 0|1 >>
 451
 452 This option is only valid when the C<$output> parameter is a filehandle. If
 453 specified, and the value is true, it will result in the C<$output> being
 454 closed once either the C<close> method is called or the C<IO::Compress::Bzip2>
 455 object is destroyed.
 456
 457 This parameter defaults to 0.
 458
 459 =item C<< Append => 0|1 >>
 460
 461 Opens C<$output> in append mode.
 462
 463 The behaviour of this option is dependent on the type of C<$output>.
 464
 465 =over 5
 466
 467 =item * A Buffer
 468
 469 If C<$output> is a buffer and C<Append> is enabled, all compressed data
 470 will be append to the end if C<$output>. Otherwise C<$output> will be
 471 cleared before any data is written to it.
 472
 473 =item * A Filename
 474
 475 If C<$output> is a filename and C<Append> is enabled, the file will be
 476 opened in append mode. Otherwise the contents of the file, if any, will be
 477 truncated before any compressed data is written to it.
 478
 479 =item * A Filehandle
 480
 481 If C<$output> is a filehandle, the file pointer will be positioned to the
 482 end of the file via a call to C<seek> before any compressed data is written
 483 to it.  Otherwise the file pointer will not be moved.
 484
 485 =back
 486
 487 This parameter defaults to 0.
 488
 489 =item C<< BlockSize100K => number >>
 490
 491 Specify the number of 100K blocks bzip2 uses during compression.
 492
 493 Valid values are from 1 to 9, where 9 is best compression.
 494
 495 The default is 1.
 496
 497 =item C<< WorkFactor => number >>
 498
 499 Specifies how much effort bzip2 should take before resorting to a slower
 500 fallback compression algorithm.
 501
 502 Valid values range from 0 to 250, where 0 means use the default value 30.
 503
 504 The default is 0.
 505
 506 =item C<< Strict => 0|1 >>
 507
 508 This is a placeholder option.
 509
 510 =back
 511
 512 =head2 Examples
 513
 514 TODO
 515
 516 =head1 Methods
 517
 518 =head2 print
 519
 520 Usage is
 521
 522     $z->print($data)
 523     print $z $data
 524
 525 Compresses and outputs the contents of the C<$data> parameter. This
 526 has the same behaviour as the C<print> built-in.
 527
 528 Returns true if successful.
 529
 530 =head2 printf
 531
 532 Usage is
 533
 534     $z->printf($format, $data)
 535     printf $z $format, $data
 536
 537 Compresses and outputs the contents of the C<$data> parameter.
 538
 539 Returns true if successful.
 540
 541 =head2 syswrite
 542
 543 Usage is
 544
 545     $z->syswrite $data
 546     $z->syswrite $data, $length
 547     $z->syswrite $data, $length, $offset
 548
 549 Compresses and outputs the contents of the C<$data> parameter.
 550
 551 Returns the number of uncompressed bytes written, or C<undef> if
 552 unsuccessful.
 553
 554 =head2 write
 555
 556 Usage is
 557
 558     $z->write $data
 559     $z->write $data, $length
 560     $z->write $data, $length, $offset
 561
 562 Compresses and outputs the contents of the C<$data> parameter.
 563
 564 Returns the number of uncompressed bytes written, or C<undef> if
 565 unsuccessful.
 566
 567 =head2 flush
 568
 569 Usage is
 570
 571     $z->flush;
 572
 573 Flushes any pending compressed data to the output file/buffer.
 574
 575 TODO
 576
 577 Returns true on success.
 578
 579 =head2 tell
 580
 581 Usage is
 582
 583     $z->tell()
 584     tell $z
 585
 586 Returns the uncompressed file offset.
 587
 588 =head2 eof
 589
 590 Usage is
 591
 592     $z->eof();
 593     eof($z);
 594
 595 Returns true if the C<close> method has been called.
 596
 597 =head2 seek
 598
 599     $z->seek($position, $whence);
 600     seek($z, $position, $whence);
 601
 602 Provides a sub-set of the C<seek> functionality, with the restriction
 603 that it is only legal to seek forward in the output file/buffer.
 604 It is a fatal error to attempt to seek backward.
 605
 606 Empty parts of the file/buffer will have NULL (0x00) bytes written to them.
 607
 608 The C<$whence> parameter takes one the usual values, namely SEEK_SET,
 609 SEEK_CUR or SEEK_END.
 610
 611 Returns 1 on success, 0 on failure.
 612
 613 =head2 binmode
 614
 615 Usage is
 616
 617     $z->binmode
 618     binmode $z ;
 619
 620 This is a noop provided for completeness.
 621
 622 =head2 opened
 623
 624     $z->opened()
 625
 626 Returns true if the object currently refers to a opened file/buffer.
 627
 628 =head2 autoflush
 629
 630     my $prev = $z->autoflush()
 631     my $prev = $z->autoflush(EXPR)
 632
 633 If the C<$z> object is associated with a file or a filehandle, this method
 634 returns the current autoflush setting for the underlying filehandle. If
 635 C<EXPR> is present, and is non-zero, it will enable flushing after every
 636 write/print operation.
 637
 638 If C<$z> is associated with a buffer, this method has no effect and always
 639 returns C<undef>.
 640
 641 B<Note> that the special variable C<$|> B<cannot> be used to set or
 642 retrieve the autoflush setting.
 643
 644 =head2 input_line_number
 645
 646     $z->input_line_number()
 647     $z->input_line_number(EXPR)
 648
 649 This method always returns C<undef> when compressing.
 650
 651 =head2 fileno
 652
 653     $z->fileno()
 654     fileno($z)
 655
 656 If the C<$z> object is associated with a file or a filehandle, C<fileno>
 657 will return the underlying file descriptor. Once the C<close> method is
 658 called C<fileno> will return C<undef>.
 659
 660 If the C<$z> object is is associated with a buffer, this method will return
 661 C<undef>.
 662
 663 =head2 close
 664
 665     $z->close() ;
 666     close $z ;
 667
 668 Flushes any pending compressed data and then closes the output file/buffer.
 669
 670 For most versions of Perl this method will be automatically invoked if
 671 the IO::Compress::Bzip2 object is destroyed (either explicitly or by the
 672 variable with the reference to the object going out of scope). The
 673 exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In
 674 these cases, the C<close> method will be called automatically, but
 675 not until global destruction of all live objects when the program is
 676 terminating.
 677
 678 Therefore, if you want your scripts to be able to run on all versions
 679 of Perl, you should call C<close> explicitly and not rely on automatic
 680 closing.
 681
 682 Returns true on success, otherwise 0.
 683
 684 If the C<AutoClose> option has been enabled when the IO::Compress::Bzip2
 685 object was created, and the object is associated with a file, the
 686 underlying file will also be closed.
 687
 688 =head2 newStream([OPTS])
 689
 690 Usage is
 691
 692     $z->newStream( [OPTS] )
 693
 694 Closes the current compressed data stream and starts a new one.
 695
 696 OPTS consists of any of the the options that are available when creating
 697 the C<$z> object.
 698
 699 See the L</"Constructor Options"> section for more details.
 700
 701 =head1 Importing
 702
 703 No symbolic constants are required by this IO::Compress::Bzip2 at present.
 704
 705 =over 5
 706
 707 =item :all
 708
 709 Imports C<bzip2> and C<$Bzip2Error>.
 710 Same as doing this
 711
 712     use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
 713
 714
 715
 716 =back
 717
 718 =head1 EXAMPLES
 719
 720 =head2 Apache::GZip Revisited
 721
 722 See L<IO::Compress::Bzip2::FAQ|IO::Compress::Bzip2::FAQ/"Apache::GZip Revisited">
 723
 724
 725
 726 =head2 Working with Net::FTP
 727
 728 See L<IO::Compress::Bzip2::FAQ|IO::Compress::Bzip2::FAQ/"Compressed files and Net::FTP">
 729
 730 =head1 SEE ALSO
 731
 732 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::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>
 733
 734 L<Compress::Zlib::FAQ|Compress::Zlib::FAQ>
 735
 736 L<File::GlobMapper|File::GlobMapper>, L<Archive::Zip|Archive::Zip>,
 737 L<Archive::Tar|Archive::Tar>,
 738 L<IO::Zlib|IO::Zlib>
 739
 740 The primary site for the bzip2 program is F<http://www.bzip.org>.
 741
 742 See the module L<Compress::Bzip2|Compress::Bzip2>
 743
 744 =head1 AUTHOR
 745
 746 This module was written by Paul Marquess, F<pmqs@cpan.org>.
 747
 748 =head1 MODIFICATION HISTORY
 749
 750 See the Changes file.
 751
 752 =head1 COPYRIGHT AND LICENSE
 753
 754 Copyright (c) 2005-2008 Paul Marquess. All rights reserved.
 755
 756 This program is free software; you can redistribute it and/or
 757 modify it under the same terms as Perl itself.
 758