2 package Compress::Raw::Bzip2;
13 our ($VERSION, $XS_VERSION, @ISA, @EXPORT, $AUTOLOAD);
16 $XS_VERSION = $VERSION;
17 $VERSION = eval $VERSION;
20 # Items to export into callers namespace by default. Note: do not export
21 # names by default without a very good reason. Use EXPORT_OK instead.
22 # Do not simply export all your public functions/methods/constants.
47 ($constname = $AUTOLOAD) =~ s/.*:://;
48 my ($error, $val) = constant($constname);
49 Carp::croak $error if $error;
51 *{$AUTOLOAD} = sub { $val };
56 use constant FLAG_APPEND => 1 ;
57 use constant FLAG_CRC => 2 ;
58 use constant FLAG_ADLER => 4 ;
59 use constant FLAG_CONSUME_INPUT => 8 ;
63 XSLoader::load('Compress::Raw::Bzip2', $XS_VERSION);
68 local @ISA = qw(DynaLoader);
69 bootstrap Compress::Raw::Bzip2 $XS_VERSION ;
72 #sub Compress::Raw::Bzip2::new
75 # my ($ptr, $status) = _new(@_);
76 # return wantarray ? (undef, $status) : undef
78 # my $obj = bless [$ptr], $class ;
79 # return wantarray ? ($obj, $status) : $obj;
82 #package Compress::Raw::Bunzip2 ;
84 #sub Compress::Raw::Bunzip2::new
87 # my ($ptr, $status) = _new(@_);
88 # return wantarray ? (undef, $status) : undef
90 # my $obj = bless [$ptr], $class ;
91 # return wantarray ? ($obj, $status) : $obj;
94 package Compress::Raw::Bzip2;
103 Compress::Raw::Bzip2 - Low-Level Interface to bzip2 compression library
107 use Compress::Raw::Bzip2 ;
109 my ($bz, $status) = new Compress::Raw::Bzip2 [OPTS]
110 or die "Cannot create bzip2 object: $bzerno\n";
112 $status = $bz->bzdeflate($input, $output);
113 $status = $bz->bzflush($output);
114 $status = $bz->bzclose($output);
116 my ($bz, $status) = new Compress::Raw::Bunzip2 [OPTS]
117 or die "Cannot create bunzip2 object: $bzerno\n";
119 $status = $bz->bzinflate($input, $output);
121 my $version = Compress::Raw::Bzip2::bzlibversion();
125 C<Compress::Raw::Bzip2> provides an interface to the in-memory
126 compression/uncompression functions from the bzip2 compression library.
128 Although the primary purpose for the existence of C<Compress::Raw::Bzip2>
129 is for use by the C<IO::Compress::Bzip2> and C<IO::Compress::Bunzip2>
130 modules, it can be used on its own for simple compression/uncompression
135 =head2 ($z, $status) = new Compress::Raw::Bzip2 $appendOutput, $blockSize100k, $workfactor;
137 Creates a new compression object.
139 If successful, it will return the initialised compression object, C<$z>
140 and a C<$status> of C<BZ_OK> in a list context. In scalar context it
141 returns the deflation object, C<$z>, only.
143 If not successful, the returned compression object, C<$z>, will be
144 I<undef> and C<$status> will hold the a I<bzip2> error code.
146 Below is a list of the valid options:
150 =item B<$appendOutput>
152 Controls whether the compressed data is appended to the output buffer in
153 the C<bzdeflate>, C<bzflush> and C<bzclose> methods.
157 =item B<$blockSize100k>
159 To quote the bzip2 documentation
161 blockSize100k specifies the block size to be used for compression. It
162 should be a value between 1 and 9 inclusive, and the actual block size
163 used is 100000 x this figure. 9 gives the best compression but takes
170 To quote the bzip2 documentation
172 This parameter controls how the compression phase behaves when
173 presented with worst case, highly repetitive, input data. If
174 compression runs into difficulties caused by repetitive data, the
175 library switches from the standard sorting algorithm to a fallback
176 algorithm. The fallback is slower than the standard algorithm by
177 perhaps a factor of three, but always behaves reasonably, no matter how
180 Lower values of workFactor reduce the amount of effort the standard
181 algorithm will expend before resorting to the fallback. You should set
182 this parameter carefully; too low, and many inputs will be handled by
183 the fallback algorithm and so compress rather slowly, too high, and
184 your average-to-worst case compression times can become very large. The
185 default value of 30 gives reasonable behaviour over a wide range of
188 Allowable values range from 0 to 250 inclusive. 0 is a special case,
189 equivalent to using the default value of 30.
195 =head2 $status = $bz->bzdeflate($input, $output);
197 Reads the contents of C<$input>, compresses it and writes the compressed
200 Returns C<BZ_RUN_OK> on success and a C<bzip2> error code on failure.
202 If C<appendOutput> is enabled in the constructor for the bzip2 object, the
203 compressed data will be appended to C<$output>. If not enabled, C<$output>
204 will be truncated before the compressed data is written to it.
206 =head2 $status = $bz->bzflush($output);
208 Flushes any pending compressed data to C<$output>.
210 Returns C<BZ_RUN_OK> on success and a C<bzip2> error code on failure.
212 =head2 $status = $bz->bzclose($output);
214 Terminates the compressed data stream and flushes any pending compressed
217 Returns C<BZ_STREAM_END> on success and a C<bzip2> error code on failure.
223 =head2 ($z, $status) = new Compress::Raw::Bunzip2 $appendOutput, $consumeInput, $small;
225 If successful, it will return the initialised uncompression object, C<$z>
226 and a C<$status> of C<BZ_OK> in a list context. In scalar context it
227 returns the deflation object, C<$z>, only.
229 If not successful, the returned uncompression object, C<$z>, will be
230 I<undef> and C<$status> will hold the a I<bzip2> error code.
232 Below is a list of the valid options:
236 =item B<$appendOutput>
238 Controls whether the compressed data is appended to the output buffer in the
239 C<bzinflate>, C<bzflush> and C<bzclose> methods.
243 =item B<$consumeInput>
247 To quote the bzip2 documentation
249 If small is nonzero, the library will use an alternative decompression
250 algorithm which uses less memory but at the cost of decompressing more
251 slowly (roughly speaking, half the speed, but the maximum memory
252 requirement drops to around 2300k).
258 =head2 $status = $z->bzinflate($input, $output);
260 Uncompresses C<$input> and writes the uncompressed data to C<$output>.
262 Returns C<BZ_OK> if the uncompression was successful, but the end of the
263 compressed data stream has not been reached. Returns C<BZ_STREAM_END> on
264 successful uncompression and the end of the compression stream has been
267 If C<consumeInput> is enabled in the constructor for the bunzip2 object,
268 C<$input> will have all compressed data removed from it after
269 uncompression. On C<BZ_OK> return this will mean that C<$input> will be an
270 empty string; when C<BZ_STREAM_END> C<$input> will either be an empty
271 string or will contain whatever data immediately followed the compressed
274 If C<appendOutput> is enabled in the constructor for the bunzip2 object,
275 the uncompressed data will be appended to C<$output>. If not enabled,
276 C<$output> will be truncated before the uncompressed data is written to it.
280 The following bzip2 constants are exported by this module
303 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::Lzop>, L<IO::Uncompress::UnLzop>, L<IO::Compress::Lzf>, L<IO::Uncompress::UnLzf>, L<IO::Uncompress::AnyInflate>, L<IO::Uncompress::AnyUncompress>
305 L<Compress::Zlib::FAQ|Compress::Zlib::FAQ>
307 L<File::GlobMapper|File::GlobMapper>, L<Archive::Zip|Archive::Zip>,
308 L<Archive::Tar|Archive::Tar>,
311 The primary site for the bzip2 program is F<http://www.bzip.org>.
313 See the module L<Compress::Bzip2|Compress::Bzip2>
317 This module was written by Paul Marquess, F<pmqs@cpan.org>.
319 =head1 MODIFICATION HISTORY
321 See the Changes file.
323 =head1 COPYRIGHT AND LICENSE
325 Copyright (c) 2005-2008 Paul Marquess. All rights reserved.
327 This program is free software; you can redistribute it and/or
328 modify it under the same terms as Perl itself.