1 package IO::Compress::Bzip2 ;
8 use IO::Compress::Base 2.021 ;
10 use IO::Compress::Base::Common 2.021 qw(createSelfTiedObject);
11 use IO::Compress::Adapter::Bzip2 2.021 ;
15 our ($VERSION, @ISA, @EXPORT_OK, %EXPORT_TAGS, $Bzip2Error);
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');
32 my $obj = createSelfTiedObject($class, \$Bzip2Error);
33 return $obj->_create(undef, @_);
38 my $obj = createSelfTiedObject(undef, \$Bzip2Error);
54 use IO::Compress::Base::Common 2.021 qw(:Parse);
57 'BlockSize100K' => [0, 1, Parse_unsigned, 1],
58 'WorkFactor' => [0, 1, Parse_unsigned, 0],
59 'Verbosity' => [0, 1, Parse_boolean, 0],
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;
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;
94 my $BlockSize100K = $got->value('BlockSize100K');
95 my $WorkFactor = $got->value('WorkFactor');
96 my $Verbosity = $got->value('Verbosity');
98 my ($obj, $errstr, $errno) = IO::Compress::Adapter::Bzip2::mkCompObject(
99 $BlockSize100K, $WorkFactor,
102 return $self->saveErrorString(undef, $errstr, $errno)
128 return ('IO::Uncompress::Bunzip2');
145 IO::Compress::Bzip2 - Write bzip2 files/buffers
151 use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
153 my $status = bzip2 $input => $output [,OPTS]
154 or die "bzip2 failed: $Bzip2Error\n";
156 my $z = new IO::Compress::Bzip2 $output [,OPTS]
157 or die "bzip2 failed: $Bzip2Error\n";
160 $z->printf($format, $string);
162 $z->syswrite($string [, $length, $offset]);
166 $z->seek($position, $whence);
171 $z->input_line_number();
172 $z->newStream( [OPTS] );
181 printf $z $format, $string;
184 seek $z, $position, $whence
192 This module provides a Perl interface that allows writing bzip2
193 compressed data to files or buffer.
195 For reading bzip2 files/buffers, see the companion module
196 L<IO::Uncompress::Bunzip2|IO::Uncompress::Bunzip2>.
198 =head1 Functional Interface
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">
205 use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
207 bzip2 $input => $output [,OPTS]
208 or die "bzip2 failed: $Bzip2Error\n";
210 The functional interface needs Perl5.005 or better.
212 =head2 bzip2 $input => $output [, OPTS]
214 C<bzip2> expects at least two parameters, C<$input> and C<$output>.
216 =head3 The C<$input> parameter
218 The parameter, C<$input>, is used to define the source of
219 the uncompressed data.
221 It can take one of the following forms:
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.
233 If the C<$input> parameter is a filehandle, the input data will be
235 The string '-' can be used as an alias for standard input.
237 =item A scalar reference
239 If C<$input> is a scalar reference, the input data will be read
242 =item An array reference
244 If C<$input> is an array reference, each element in the array must be a
247 The input data will be read from each file in turn.
249 The complete array will be walked to ensure that it only
250 contains valid filenames before any data is compressed.
252 =item An Input FileGlob string
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.
258 If the fileglob does not match any files ...
260 See L<File::GlobMapper|File::GlobMapper> for more details.
264 If the C<$input> parameter is any other type, C<undef> will be returned.
266 =head3 The C<$output> parameter
268 The parameter C<$output> is used to control the destination of the
269 compressed data. This parameter can take one of these forms.
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.
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.
285 =item A scalar reference
287 If C<$output> is a scalar reference, the compressed data will be
288 stored in C<$$output>.
290 =item An Array Reference
292 If C<$output> is an array reference, the compressed data will be
293 pushed onto the array.
295 =item An Output FileGlob
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.
301 When C<$output> is an fileglob string, C<$input> must also be a fileglob
302 string. Anything else is an error.
306 If the C<$output> parameter is any other type, C<undef> will be returned.
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.
314 =head2 Optional Parameters
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.
322 =item C<< AutoClose => 0|1 >>
324 This option applies to any input or output data streams to
325 C<bzip2> that are filehandles.
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
331 This parameter defaults to 0.
333 =item C<< BinModeIn => 0|1 >>
335 When reading from a file or filehandle, set C<binmode> before reading.
339 =item C<< Append => 0|1 >>
347 To read the contents of the file C<file1.txt> and write the compressed
348 data to the file C<file1.txt.bz2>.
352 use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
354 my $input = "file1.txt";
355 bzip2 $input => "$input.bz2"
356 or die "bzip2 failed: $Bzip2Error\n";
358 To read from an existing Perl filehandle, C<$input>, and write the
359 compressed data to a buffer, C<$buffer>.
363 use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
366 my $input = new IO::File "<file1.txt"
367 or die "Cannot open 'file1.txt': $!\n" ;
369 bzip2 $input => \$buffer
370 or die "bzip2 failed: $Bzip2Error\n";
372 To compress all files in the directory "/my/home" that match "*.txt"
373 and store the compressed data in the same directory
377 use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
379 bzip2 '</my/home/*.txt>' => '<*.bz2>'
380 or die "bzip2 failed: $Bzip2Error\n";
382 and if you want to compress each file one at a time, this will do the trick
386 use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
388 for my $input ( glob "/my/home/*.txt" )
390 my $output = "$input.bz2" ;
391 bzip2 $input => $output
392 or die "Error compressing '$input': $Bzip2Error\n";
399 The format of the constructor for C<IO::Compress::Bzip2> is shown below
401 my $z = new IO::Compress::Bzip2 $output [,OPTS]
402 or die "IO::Compress::Bzip2 failed: $Bzip2Error\n";
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.
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
411 For example, to write to a compressed file/buffer you can use either of
414 $z->print("hello world\n");
415 print $z "hello world\n";
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.
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.
430 If the C<$output> parameter is a filehandle, the compressed data will be
432 The string '-' can be used as an alias for standard output.
434 =item A scalar reference
436 If C<$output> is a scalar reference, the compressed data will be stored
441 If the C<$output> parameter is any other type, C<IO::Compress::Bzip2>::new will
444 =head2 Constructor Options
446 C<OPTS> is any combination of the following options:
450 =item C<< AutoClose => 0|1 >>
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>
457 This parameter defaults to 0.
459 =item C<< Append => 0|1 >>
461 Opens C<$output> in append mode.
463 The behaviour of this option is dependent on the type of C<$output>.
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.
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.
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.
487 This parameter defaults to 0.
489 =item C<< BlockSize100K => number >>
491 Specify the number of 100K blocks bzip2 uses during compression.
493 Valid values are from 1 to 9, where 9 is best compression.
497 =item C<< WorkFactor => number >>
499 Specifies how much effort bzip2 should take before resorting to a slower
500 fallback compression algorithm.
502 Valid values range from 0 to 250, where 0 means use the default value 30.
506 =item C<< Strict => 0|1 >>
508 This is a placeholder option.
525 Compresses and outputs the contents of the C<$data> parameter. This
526 has the same behaviour as the C<print> built-in.
528 Returns true if successful.
534 $z->printf($format, $data)
535 printf $z $format, $data
537 Compresses and outputs the contents of the C<$data> parameter.
539 Returns true if successful.
546 $z->syswrite $data, $length
547 $z->syswrite $data, $length, $offset
549 Compresses and outputs the contents of the C<$data> parameter.
551 Returns the number of uncompressed bytes written, or C<undef> if
559 $z->write $data, $length
560 $z->write $data, $length, $offset
562 Compresses and outputs the contents of the C<$data> parameter.
564 Returns the number of uncompressed bytes written, or C<undef> if
573 Flushes any pending compressed data to the output file/buffer.
577 Returns true on success.
586 Returns the uncompressed file offset.
595 Returns true if the C<close> method has been called.
599 $z->seek($position, $whence);
600 seek($z, $position, $whence);
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.
606 Empty parts of the file/buffer will have NULL (0x00) bytes written to them.
608 The C<$whence> parameter takes one the usual values, namely SEEK_SET,
609 SEEK_CUR or SEEK_END.
611 Returns 1 on success, 0 on failure.
620 This is a noop provided for completeness.
626 Returns true if the object currently refers to a opened file/buffer.
630 my $prev = $z->autoflush()
631 my $prev = $z->autoflush(EXPR)
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.
638 If C<$z> is associated with a buffer, this method has no effect and always
641 B<Note> that the special variable C<$|> B<cannot> be used to set or
642 retrieve the autoflush setting.
644 =head2 input_line_number
646 $z->input_line_number()
647 $z->input_line_number(EXPR)
649 This method always returns C<undef> when compressing.
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>.
660 If the C<$z> object is is associated with a buffer, this method will return
668 Flushes any pending compressed data and then closes the output file/buffer.
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
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
682 Returns true on success, otherwise 0.
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.
688 =head2 newStream([OPTS])
692 $z->newStream( [OPTS] )
694 Closes the current compressed data stream and starts a new one.
696 OPTS consists of any of the the options that are available when creating
699 See the L</"Constructor Options"> section for more details.
703 No symbolic constants are required by this IO::Compress::Bzip2 at present.
709 Imports C<bzip2> and C<$Bzip2Error>.
712 use IO::Compress::Bzip2 qw(bzip2 $Bzip2Error) ;
720 =head2 Apache::GZip Revisited
722 See L<IO::Compress::Bzip2::FAQ|IO::Compress::Bzip2::FAQ/"Apache::GZip Revisited">
726 =head2 Working with Net::FTP
728 See L<IO::Compress::Bzip2::FAQ|IO::Compress::Bzip2::FAQ/"Compressed files and Net::FTP">
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>
734 L<Compress::Zlib::FAQ|Compress::Zlib::FAQ>
736 L<File::GlobMapper|File::GlobMapper>, L<Archive::Zip|Archive::Zip>,
737 L<Archive::Tar|Archive::Tar>,
740 The primary site for the bzip2 program is F<http://www.bzip.org>.
742 See the module L<Compress::Bzip2|Compress::Bzip2>
746 This module was written by Paul Marquess, F<pmqs@cpan.org>.
748 =head1 MODIFICATION HISTORY
750 See the Changes file.
752 =head1 COPYRIGHT AND LICENSE
754 Copyright (c) 2005-2008 Paul Marquess. All rights reserved.
756 This program is free software; you can redistribute it and/or
757 modify it under the same terms as Perl itself.