NAME

Compress::Bzip2 - interface to the bzip2 compression library

SYNOPSIS

use Compress::Bzip2;

$dest = Compress::Bzip2::compress($source, [$level]);
$dest = Compress::Bzip2::decompress($source);

DESCRIPTION

The Compress::Bzip2 module provides a Perl interface to the Bzip2 compression library (see "AUTHOR" for details about where to get Bzip2). A relevant subset of the functionality provided by Bzip2 is available in Compress::Bzip2.

You may pass in a reference to a string wherever a string is required.

You can retrieve the library version using the version function.

COMPRESSION FUNCTIONS

$dest = Compress::Bzip2::compress($string)

Compress a string using the default compression level, returning a string containing compressed data.

$dest = Compress::Bzip2::compress($string, $level)

Compress string, using the chosen compression level (either 1 or 9). Return a string containing the compressed data.

On error undef is returned.

DECOMPRESSION FUNCTIONS

$dest = Compress::Bzip2::decompress($string)

Decompress the data in string, returning a string containing the decompressed data.

On error undef is returned.

ERROR STATUS

If a function reports an error by returning undef, call error to get the error string. In list context, returns a list of (string, libbz2 code).

if(not defined $dest)
{
    print "compression failed: ".Compress::Bzip2::error();
}

STREAMING COMPRESSION

To compress a larger volume of data, the streamed compression interface may be of use. For both compression and decompression, you create a stream object, add data to it, then call finish when done:

my $stream = Compress::Bzip2::compress_init();

while(my $data = read_data())
{
    write_data($stream->add($data));
}

write_data($stream->finish());

Note that if you want to be able to decompress the result using the decompress method, you need to call the prefix method and prefix the result:

my $original = Compress::Bzip2::decompress($stream->prefix().$output);

The streaming decompression interface is similar; just replace compress_init with decompress_init. The optional parameters each takes as well as some other methods on the stream object are described below:

compress_init

Takes named parameters:

level

1 or 9, as for compress (defaults to 1)

workFactor

bzip2 library work factor (0-250; if missing or 0 defaults to 30)

buffer

buffer size to use (defaults to 8192 - 8K)

decompress_init

Takes named parameters:

small

if set (1), use alternative algorithm (slower but uses less memory) (default 0)

buffer

buffer size to use (defaults to 8192 - 8K)

add ( string )

Add data to be compressed/decompressed. Returns whatever output is available (possibly none, if it's still buffering it), or undef on error.

finish ( [string] )

Finish the operation; takes an optional final data string. Whatever is returned completes the output; returns undef on error.

error

Like the function, but applies to the current object only. Note that errors in a stream object are also returned by the function.

input_size

Total bytes passed to the stream.

output_size

Total bytes received from the stream.

AUTHOR

The Compress::Bzip2 module was written by Gawdi Azem azemgi@rupert.informatik.uni-stuttgart.de and is now maintained by Marco Carnut kiko@tempest.com.br. The streaming interface and error information were added by David Robins dbrobins@davidrobins.net.

MODIFICATION HISTORY

1.00 First public release of Compress::Bzip2.

1.02 Added BZ2_ prefixes so that it works with libbz2 versions >1.0

1.03 Added error reporting, and streaming functions, fixed some compression errors, added tests.

cpanm Compress::Bzip2

perl -MCPAN -e shell
install Compress::Bzip2