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, $limitOutput;
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).
256 =item B<$limitOutput>
258 The C<LimitOutput> option changes the behavior of the C<< $i->bzinflate >>
259 method so that the amount of memory used by the output buffer can be
262 When C<LimitOutput> is used the size of the output buffer used will either
263 be the 16k or the amount of memory already allocated to C<$output>,
264 whichever is larger. Predicting the output size available is tricky, so
265 don't rely on getting an exact output buffer size.
267 When C<LimitOutout> is not specified C<< $i->bzinflate >> will use as much
268 memory as it takes to write all the uncompressed data it creates by
269 uncompressing the input buffer.
271 If C<LimitOutput> is enabled, the C<ConsumeInput> option will also be
274 This option defaults to false.
278 =head2 $status = $z->bzinflate($input, $output);
280 Uncompresses C<$input> and writes the uncompressed data to C<$output>.
282 Returns C<BZ_OK> if the uncompression was successful, but the end of the
283 compressed data stream has not been reached. Returns C<BZ_STREAM_END> on
284 successful uncompression and the end of the compression stream has been
287 If C<consumeInput> is enabled in the constructor for the bunzip2 object,
288 C<$input> will have all compressed data removed from it after
289 uncompression. On C<BZ_OK> return this will mean that C<$input> will be an
290 empty string; when C<BZ_STREAM_END> C<$input> will either be an empty
291 string or will contain whatever data immediately followed the compressed
294 If C<appendOutput> is enabled in the constructor for the bunzip2 object,
295 the uncompressed data will be appended to C<$output>. If not enabled,
296 C<$output> will be truncated before the uncompressed data is written to it.
300 =head2 my $version = Compress::Raw::Bzip2::bzlibversion();
302 Returns the version of the underlying bzip2 library.
306 The following bzip2 constants are exported by this module
329 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::Lzop>, L<IO::Uncompress::UnLzop>, L<IO::Compress::Lzf>, L<IO::Uncompress::UnLzf>, L<IO::Uncompress::AnyInflate>, L<IO::Uncompress::AnyUncompress>
331 L<Compress::Zlib::FAQ|Compress::Zlib::FAQ>
333 L<File::GlobMapper|File::GlobMapper>, L<Archive::Zip|Archive::Zip>,
334 L<Archive::Tar|Archive::Tar>,
337 The primary site for the bzip2 program is F<http://www.bzip.org>.
339 See the module L<Compress::Bzip2|Compress::Bzip2>
343 This module was written by Paul Marquess, F<pmqs@cpan.org>.
345 =head1 MODIFICATION HISTORY
347 See the Changes file.
349 =head1 COPYRIGHT AND LICENSE
351 Copyright (c) 2005-2010 Paul Marquess. All rights reserved.
353 This program is free software; you can redistribute it and/or
354 modify it under the same terms as Perl itself.