391 lines
11 KiB
Perl
391 lines
11 KiB
Perl
|
|
package Compress::Raw::Bzip2;
|
|
|
|
use strict ;
|
|
use warnings ;
|
|
|
|
require 5.006 ;
|
|
require Exporter;
|
|
use Carp ;
|
|
|
|
use bytes ;
|
|
our ($VERSION, $XS_VERSION, @ISA, @EXPORT, $AUTOLOAD);
|
|
|
|
$VERSION = '2.100';
|
|
$XS_VERSION = $VERSION;
|
|
$VERSION = eval $VERSION;
|
|
|
|
@ISA = qw(Exporter);
|
|
# Items to export into callers namespace by default. Note: do not export
|
|
# names by default without a very good reason. Use EXPORT_OK instead.
|
|
# Do not simply export all your public functions/methods/constants.
|
|
@EXPORT = qw(
|
|
BZ_RUN
|
|
BZ_FLUSH
|
|
BZ_FINISH
|
|
|
|
BZ_OK
|
|
BZ_RUN_OK
|
|
BZ_FLUSH_OK
|
|
BZ_FINISH_OK
|
|
BZ_STREAM_END
|
|
BZ_SEQUENCE_ERROR
|
|
BZ_PARAM_ERROR
|
|
BZ_MEM_ERROR
|
|
BZ_DATA_ERROR
|
|
BZ_DATA_ERROR_MAGIC
|
|
BZ_IO_ERROR
|
|
BZ_UNEXPECTED_EOF
|
|
BZ_OUTBUFF_FULL
|
|
BZ_CONFIG_ERROR
|
|
|
|
);
|
|
|
|
sub AUTOLOAD {
|
|
my($constname);
|
|
($constname = $AUTOLOAD) =~ s/.*:://;
|
|
my ($error, $val) = constant($constname);
|
|
Carp::croak $error if $error;
|
|
no strict 'refs';
|
|
*{$AUTOLOAD} = sub { $val };
|
|
goto &{$AUTOLOAD};
|
|
|
|
}
|
|
|
|
use constant FLAG_APPEND => 1 ;
|
|
use constant FLAG_CRC => 2 ;
|
|
use constant FLAG_ADLER => 4 ;
|
|
use constant FLAG_CONSUME_INPUT => 8 ;
|
|
|
|
eval {
|
|
require XSLoader;
|
|
XSLoader::load('Compress::Raw::Bzip2', $XS_VERSION);
|
|
1;
|
|
}
|
|
or do {
|
|
require DynaLoader;
|
|
local @ISA = qw(DynaLoader);
|
|
bootstrap Compress::Raw::Bzip2 $XS_VERSION ;
|
|
};
|
|
|
|
#sub Compress::Raw::Bzip2::new
|
|
#{
|
|
# my $class = shift ;
|
|
# my ($ptr, $status) = _new(@_);
|
|
# return wantarray ? (undef, $status) : undef
|
|
# unless $ptr ;
|
|
# my $obj = bless [$ptr], $class ;
|
|
# return wantarray ? ($obj, $status) : $obj;
|
|
#}
|
|
#
|
|
#package Compress::Raw::Bunzip2 ;
|
|
#
|
|
#sub Compress::Raw::Bunzip2::new
|
|
#{
|
|
# my $class = shift ;
|
|
# my ($ptr, $status) = _new(@_);
|
|
# return wantarray ? (undef, $status) : undef
|
|
# unless $ptr ;
|
|
# my $obj = bless [$ptr], $class ;
|
|
# return wantarray ? ($obj, $status) : $obj;
|
|
#}
|
|
|
|
sub Compress::Raw::Bzip2::STORABLE_freeze
|
|
{
|
|
my $type = ref shift;
|
|
croak "Cannot freeze $type object\n";
|
|
}
|
|
|
|
sub Compress::Raw::Bzip2::STORABLE_thaw
|
|
{
|
|
my $type = ref shift;
|
|
croak "Cannot thaw $type object\n";
|
|
}
|
|
|
|
sub Compress::Raw::Bunzip2::STORABLE_freeze
|
|
{
|
|
my $type = ref shift;
|
|
croak "Cannot freeze $type object\n";
|
|
}
|
|
|
|
sub Compress::Raw::Bunzip2::STORABLE_thaw
|
|
{
|
|
my $type = ref shift;
|
|
croak "Cannot thaw $type object\n";
|
|
}
|
|
|
|
|
|
package Compress::Raw::Bzip2;
|
|
|
|
1;
|
|
|
|
__END__
|
|
|
|
|
|
=head1 NAME
|
|
|
|
Compress::Raw::Bzip2 - Low-Level Interface to bzip2 compression library
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
use Compress::Raw::Bzip2 ;
|
|
|
|
my ($bz, $status) = new Compress::Raw::Bzip2 [OPTS]
|
|
or die "Cannot create bzip2 object: $bzerno\n";
|
|
|
|
$status = $bz->bzdeflate($input, $output);
|
|
$status = $bz->bzflush($output);
|
|
$status = $bz->bzclose($output);
|
|
|
|
my ($bz, $status) = new Compress::Raw::Bunzip2 [OPTS]
|
|
or die "Cannot create bunzip2 object: $bzerno\n";
|
|
|
|
$status = $bz->bzinflate($input, $output);
|
|
|
|
my $version = Compress::Raw::Bzip2::bzlibversion();
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
C<Compress::Raw::Bzip2> provides an interface to the in-memory
|
|
compression/uncompression functions from the bzip2 compression library.
|
|
|
|
Although the primary purpose for the existence of C<Compress::Raw::Bzip2>
|
|
is for use by the C<IO::Compress::Bzip2> and C<IO::Compress::Bunzip2>
|
|
modules, it can be used on its own for simple compression/uncompression
|
|
tasks.
|
|
|
|
=head1 Compression
|
|
|
|
=head2 ($z, $status) = new Compress::Raw::Bzip2 $appendOutput, $blockSize100k, $workfactor;
|
|
|
|
Creates a new compression object.
|
|
|
|
If successful, it will return the initialised compression object, C<$z>
|
|
and a C<$status> of C<BZ_OK> in a list context. In scalar context it
|
|
returns the deflation object, C<$z>, only.
|
|
|
|
If not successful, the returned compression object, C<$z>, will be
|
|
I<undef> and C<$status> will hold the a I<bzip2> error code.
|
|
|
|
Below is a list of the valid options:
|
|
|
|
=over 5
|
|
|
|
=item B<$appendOutput>
|
|
|
|
Controls whether the compressed data is appended to the output buffer in
|
|
the C<bzdeflate>, C<bzflush> and C<bzclose> methods.
|
|
|
|
Defaults to 1.
|
|
|
|
=item B<$blockSize100k>
|
|
|
|
To quote the bzip2 documentation
|
|
|
|
blockSize100k specifies the block size to be used for compression. It
|
|
should be a value between 1 and 9 inclusive, and the actual block size
|
|
used is 100000 x this figure. 9 gives the best compression but takes
|
|
most memory.
|
|
|
|
Defaults to 1.
|
|
|
|
=item B<$workfactor>
|
|
|
|
To quote the bzip2 documentation
|
|
|
|
This parameter controls how the compression phase behaves when
|
|
presented with worst case, highly repetitive, input data. If
|
|
compression runs into difficulties caused by repetitive data, the
|
|
library switches from the standard sorting algorithm to a fallback
|
|
algorithm. The fallback is slower than the standard algorithm by
|
|
perhaps a factor of three, but always behaves reasonably, no matter how
|
|
bad the input.
|
|
|
|
Lower values of workFactor reduce the amount of effort the standard
|
|
algorithm will expend before resorting to the fallback. You should set
|
|
this parameter carefully; too low, and many inputs will be handled by
|
|
the fallback algorithm and so compress rather slowly, too high, and
|
|
your average-to-worst case compression times can become very large. The
|
|
default value of 30 gives reasonable behaviour over a wide range of
|
|
circumstances.
|
|
|
|
Allowable values range from 0 to 250 inclusive. 0 is a special case,
|
|
equivalent to using the default value of 30.
|
|
|
|
Defaults to 0.
|
|
|
|
=back
|
|
|
|
=head2 $status = $bz->bzdeflate($input, $output);
|
|
|
|
Reads the contents of C<$input>, compresses it and writes the compressed
|
|
data to C<$output>.
|
|
|
|
Returns C<BZ_RUN_OK> on success and a C<bzip2> error code on failure.
|
|
|
|
If C<appendOutput> is enabled in the constructor for the bzip2 object, the
|
|
compressed data will be appended to C<$output>. If not enabled, C<$output>
|
|
will be truncated before the compressed data is written to it.
|
|
|
|
=head2 $status = $bz->bzflush($output);
|
|
|
|
Flushes any pending compressed data to C<$output>.
|
|
|
|
Returns C<BZ_RUN_OK> on success and a C<bzip2> error code on failure.
|
|
|
|
=head2 $status = $bz->bzclose($output);
|
|
|
|
Terminates the compressed data stream and flushes any pending compressed
|
|
data to C<$output>.
|
|
|
|
Returns C<BZ_STREAM_END> on success and a C<bzip2> error code on failure.
|
|
|
|
=head2 Example
|
|
|
|
=head1 Uncompression
|
|
|
|
=head2 ($z, $status) = new Compress::Raw::Bunzip2 $appendOutput, $consumeInput, $small, $verbosity, $limitOutput;
|
|
|
|
If successful, it will return the initialised uncompression object, C<$z>
|
|
and a C<$status> of C<BZ_OK> in a list context. In scalar context it
|
|
returns the deflation object, C<$z>, only.
|
|
|
|
If not successful, the returned uncompression object, C<$z>, will be
|
|
I<undef> and C<$status> will hold the a I<bzip2> error code.
|
|
|
|
Below is a list of the valid options:
|
|
|
|
=over 5
|
|
|
|
=item B<$appendOutput>
|
|
|
|
Controls whether the compressed data is appended to the output buffer in the
|
|
C<bzinflate>, C<bzflush> and C<bzclose> methods.
|
|
|
|
Defaults to 1.
|
|
|
|
=item B<$consumeInput>
|
|
|
|
=item B<$small>
|
|
|
|
To quote the bzip2 documentation
|
|
|
|
If small is nonzero, the library will use an alternative decompression
|
|
algorithm which uses less memory but at the cost of decompressing more
|
|
slowly (roughly speaking, half the speed, but the maximum memory
|
|
requirement drops to around 2300k).
|
|
|
|
Defaults to 0.
|
|
|
|
=item B<$limitOutput>
|
|
|
|
The C<LimitOutput> option changes the behavior of the C<< $i->bzinflate >>
|
|
method so that the amount of memory used by the output buffer can be
|
|
limited.
|
|
|
|
When C<LimitOutput> is used the size of the output buffer used will either
|
|
be the 16k or the amount of memory already allocated to C<$output>,
|
|
whichever is larger. Predicting the output size available is tricky, so
|
|
don't rely on getting an exact output buffer size.
|
|
|
|
When C<LimitOutout> is not specified C<< $i->bzinflate >> will use as much
|
|
memory as it takes to write all the uncompressed data it creates by
|
|
uncompressing the input buffer.
|
|
|
|
If C<LimitOutput> is enabled, the C<ConsumeInput> option will also be
|
|
enabled.
|
|
|
|
This option defaults to false.
|
|
|
|
=item B<$verbosity>
|
|
|
|
This parameter is ignored.
|
|
|
|
Defaults to 0.
|
|
|
|
=back
|
|
|
|
=head2 $status = $z->bzinflate($input, $output);
|
|
|
|
Uncompresses C<$input> and writes the uncompressed data to C<$output>.
|
|
|
|
Returns C<BZ_OK> if the uncompression was successful, but the end of the
|
|
compressed data stream has not been reached. Returns C<BZ_STREAM_END> on
|
|
successful uncompression and the end of the compression stream has been
|
|
reached.
|
|
|
|
If C<consumeInput> is enabled in the constructor for the bunzip2 object,
|
|
C<$input> will have all compressed data removed from it after
|
|
uncompression. On C<BZ_OK> return this will mean that C<$input> will be an
|
|
empty string; when C<BZ_STREAM_END> C<$input> will either be an empty
|
|
string or will contain whatever data immediately followed the compressed
|
|
data stream.
|
|
|
|
If C<appendOutput> is enabled in the constructor for the bunzip2 object,
|
|
the uncompressed data will be appended to C<$output>. If not enabled,
|
|
C<$output> will be truncated before the uncompressed data is written to it.
|
|
|
|
=head1 Misc
|
|
|
|
=head2 my $version = Compress::Raw::Bzip2::bzlibversion();
|
|
|
|
Returns the version of the underlying bzip2 library.
|
|
|
|
=head1 Constants
|
|
|
|
The following bzip2 constants are exported by this module
|
|
|
|
BZ_RUN
|
|
BZ_FLUSH
|
|
BZ_FINISH
|
|
|
|
BZ_OK
|
|
BZ_RUN_OK
|
|
BZ_FLUSH_OK
|
|
BZ_FINISH_OK
|
|
BZ_STREAM_END
|
|
BZ_SEQUENCE_ERROR
|
|
BZ_PARAM_ERROR
|
|
BZ_MEM_ERROR
|
|
BZ_DATA_ERROR
|
|
BZ_DATA_ERROR_MAGIC
|
|
BZ_IO_ERROR
|
|
BZ_UNEXPECTED_EOF
|
|
BZ_OUTBUFF_FULL
|
|
BZ_CONFIG_ERROR
|
|
|
|
=head1 SUPPORT
|
|
|
|
General feedback/questions/bug reports should be sent to
|
|
L<https://github.com/pmqs/Compress-Raw-Bzip2/issues> (preferred) or
|
|
L<https://rt.cpan.org/Public/Dist/Display.html?Name=Compress-Raw-Bzip2>.
|
|
|
|
=head1 SEE ALSO
|
|
|
|
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::Uncompress::Bunzip2>, L<IO::Compress::Lzma>, L<IO::Uncompress::UnLzma>, L<IO::Compress::Xz>, L<IO::Uncompress::UnXz>, L<IO::Compress::Lzip>, L<IO::Uncompress::UnLzip>, L<IO::Compress::Lzop>, L<IO::Uncompress::UnLzop>, L<IO::Compress::Lzf>, L<IO::Uncompress::UnLzf>, L<IO::Compress::Zstd>, L<IO::Uncompress::UnZstd>, L<IO::Uncompress::AnyInflate>, L<IO::Uncompress::AnyUncompress>
|
|
|
|
L<IO::Compress::FAQ|IO::Compress::FAQ>
|
|
|
|
L<File::GlobMapper|File::GlobMapper>, L<Archive::Zip|Archive::Zip>,
|
|
L<Archive::Tar|Archive::Tar>,
|
|
L<IO::Zlib|IO::Zlib>
|
|
|
|
The primary site for the bzip2 program is L<https://sourceware.org/bzip2/>.
|
|
|
|
See the module L<Compress::Bzip2|Compress::Bzip2>
|
|
|
|
=head1 AUTHOR
|
|
|
|
This module was written by Paul Marquess, C<pmqs@cpan.org>.
|
|
|
|
=head1 MODIFICATION HISTORY
|
|
|
|
See the Changes file.
|
|
|
|
=head1 COPYRIGHT AND LICENSE
|
|
|
|
Copyright (c) 2005-2021 Paul Marquess. All rights reserved.
|
|
|
|
This program is free software; you can redistribute it and/or
|
|
modify it under the same terms as Perl itself.
|