1
2package Compress::Raw::Bzip2;
3
4use strict ;
5use warnings ;
6
7require 5.004 ;
8require Exporter;
9use AutoLoader;
10use Carp ;
11
12use bytes ;
13our ($VERSION, $XS_VERSION, @ISA, @EXPORT, $AUTOLOAD);
14
15$VERSION = '2.031';
16$XS_VERSION = $VERSION;
17$VERSION = eval $VERSION;
18
19@ISA = qw(Exporter);
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.
23@EXPORT = qw(
24		BZ_RUN
25		BZ_FLUSH
26		BZ_FINISH
27
28		BZ_OK
29		BZ_RUN_OK
30		BZ_FLUSH_OK
31		BZ_FINISH_OK
32		BZ_STREAM_END
33		BZ_SEQUENCE_ERROR
34		BZ_PARAM_ERROR
35		BZ_MEM_ERROR
36		BZ_DATA_ERROR
37		BZ_DATA_ERROR_MAGIC
38		BZ_IO_ERROR
39		BZ_UNEXPECTED_EOF
40		BZ_OUTBUFF_FULL
41		BZ_CONFIG_ERROR
42
43    );
44
45sub AUTOLOAD {
46    my($constname);
47    ($constname = $AUTOLOAD) =~ s/.*:://;
48    my ($error, $val) = constant($constname);
49    Carp::croak $error if $error;
50    no strict 'refs';
51    *{$AUTOLOAD} = sub { $val };
52    goto &{$AUTOLOAD};
53
54}
55
56use constant FLAG_APPEND             => 1 ;
57use constant FLAG_CRC                => 2 ;
58use constant FLAG_ADLER              => 4 ;
59use constant FLAG_CONSUME_INPUT      => 8 ;
60
61eval {
62    require XSLoader;
63    XSLoader::load('Compress::Raw::Bzip2', $XS_VERSION);
64    1;
65}
66or do {
67    require DynaLoader;
68    local @ISA = qw(DynaLoader);
69    bootstrap Compress::Raw::Bzip2 $XS_VERSION ;
70};
71
72#sub Compress::Raw::Bzip2::new
73#{
74#    my $class = shift ;
75#    my ($ptr, $status) = _new(@_);
76#    return wantarray ? (undef, $status) : undef
77#        unless $ptr ;
78#    my $obj = bless [$ptr], $class ;
79#    return wantarray ? ($obj, $status) : $obj;
80#}
81#
82#package Compress::Raw::Bunzip2 ;
83#
84#sub Compress::Raw::Bunzip2::new
85#{
86#    my $class = shift ;
87#    my ($ptr, $status) = _new(@_);
88#    return wantarray ? (undef, $status) : undef
89#        unless $ptr ;
90#    my $obj = bless [$ptr], $class ;
91#    return wantarray ? ($obj, $status) : $obj;
92#}
93
94package Compress::Raw::Bzip2;
95
961;
97
98__END__
99
100
101=head1 NAME
102
103Compress::Raw::Bzip2 - Low-Level Interface to bzip2 compression library
104
105=head1 SYNOPSIS
106
107    use Compress::Raw::Bzip2 ;
108
109    my ($bz, $status) = new Compress::Raw::Bzip2 [OPTS]
110        or die "Cannot create bzip2 object: $bzerno\n";
111
112    $status = $bz->bzdeflate($input, $output);
113    $status = $bz->bzflush($output);
114    $status = $bz->bzclose($output);
115
116    my ($bz, $status) = new Compress::Raw::Bunzip2 [OPTS]
117        or die "Cannot create bunzip2 object: $bzerno\n";
118
119    $status = $bz->bzinflate($input, $output);
120
121    my $version = Compress::Raw::Bzip2::bzlibversion();
122
123=head1 DESCRIPTION
124
125C<Compress::Raw::Bzip2> provides an interface to the in-memory
126compression/uncompression functions from the bzip2 compression library.
127
128Although the primary purpose for the existence of C<Compress::Raw::Bzip2>
129is for use by the  C<IO::Compress::Bzip2> and C<IO::Compress::Bunzip2>
130modules, it can be used on its own for simple compression/uncompression
131tasks.
132
133=head1 Compression
134
135=head2 ($z, $status) = new Compress::Raw::Bzip2 $appendOutput, $blockSize100k, $workfactor;
136
137Creates a new compression object.
138
139If successful, it will return the initialised compression object, C<$z>
140and a C<$status> of C<BZ_OK> in a list context. In scalar context it
141returns the deflation object, C<$z>, only.
142
143If not successful, the returned compression object, C<$z>, will be
144I<undef> and C<$status> will hold the a I<bzip2> error code.
145
146Below is a list of the valid options:
147
148=over 5
149
150=item B<$appendOutput>
151
152Controls whether the compressed data is appended to the output buffer in
153the C<bzdeflate>, C<bzflush> and C<bzclose> methods.
154
155Defaults to 1.
156
157=item B<$blockSize100k>
158
159To quote the bzip2 documentation
160
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
164    most memory.
165
166Defaults to 1.
167
168=item B<$workfactor>
169
170To quote the bzip2 documentation
171
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
178    bad the input.
179
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
186    circumstances.
187
188    Allowable values range from 0 to 250 inclusive. 0 is a special case,
189    equivalent to using the default value of 30.
190
191Defaults to 0.
192
193=back
194
195=head2 $status = $bz->bzdeflate($input, $output);
196
197Reads the contents of C<$input>, compresses it and writes the compressed
198data to C<$output>.
199
200Returns C<BZ_RUN_OK> on success and a C<bzip2> error code on failure.
201
202If C<appendOutput> is enabled in the constructor for the bzip2 object, the
203compressed data will be appended to C<$output>. If not enabled, C<$output>
204will be truncated before the compressed data is written to it.
205
206=head2 $status = $bz->bzflush($output);
207
208Flushes any pending compressed data to C<$output>.
209
210Returns C<BZ_RUN_OK> on success and a C<bzip2> error code on failure.
211
212=head2 $status = $bz->bzclose($output);
213
214Terminates the compressed data stream and flushes any pending compressed
215data to C<$output>.
216
217Returns C<BZ_STREAM_END> on success and a C<bzip2> error code on failure.
218
219=head2 Example
220
221=head1 Uncompression
222
223=head2 ($z, $status) = new Compress::Raw::Bunzip2 $appendOutput, $consumeInput, $small, $verbosity, $limitOutput;
224
225If successful, it will return the initialised uncompression object, C<$z>
226and a C<$status> of C<BZ_OK> in a list context. In scalar context it
227returns the deflation object, C<$z>, only.
228
229If not successful, the returned uncompression object, C<$z>, will be
230I<undef> and C<$status> will hold the a I<bzip2> error code.
231
232Below is a list of the valid options:
233
234=over 5
235
236=item B<$appendOutput>
237
238Controls whether the compressed data is appended to the output buffer in the
239C<bzinflate>, C<bzflush> and C<bzclose> methods.
240
241Defaults to 1.
242
243=item B<$consumeInput>
244
245=item B<$small>
246
247To quote the bzip2 documentation
248
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).
253
254Defaults to 0.
255
256=item B<$limitOutput>
257
258The C<LimitOutput> option changes the behavior of the C<< $i->bzinflate >>
259method so that the amount of memory used by the output buffer can be
260limited.
261
262When C<LimitOutput> is used the size of the output buffer used will either
263be the 16k or the amount of memory already allocated to C<$output>,
264whichever is larger. Predicting the output size available is tricky, so
265don't rely on getting an exact output buffer size.
266
267When C<LimitOutout> is not specified C<< $i->bzinflate >> will use as much
268memory as it takes to write all the uncompressed data it creates by
269uncompressing the input buffer.
270
271If C<LimitOutput> is enabled, the C<ConsumeInput> option will also be
272enabled.
273
274This option defaults to false.
275
276=item B<$verbosity>
277
278This parameter is ignored.
279
280Defaults to 0.
281
282=back
283
284=head2 $status = $z->bzinflate($input, $output);
285
286Uncompresses C<$input> and writes the uncompressed data to C<$output>.
287
288Returns C<BZ_OK> if the uncompression was successful, but the end of the
289compressed data stream has not been reached. Returns C<BZ_STREAM_END> on
290successful uncompression and the end of the compression stream has been
291reached.
292
293If C<consumeInput> is enabled in the constructor for the bunzip2 object,
294C<$input> will have all compressed data removed from it after
295uncompression. On C<BZ_OK> return this will mean that C<$input> will be an
296empty string; when C<BZ_STREAM_END> C<$input> will either be an empty
297string or will contain whatever data immediately followed the compressed
298data stream.
299
300If C<appendOutput> is enabled in the constructor for the bunzip2 object,
301the uncompressed data will be appended to C<$output>. If not enabled,
302C<$output> will be truncated before the uncompressed data is written to it.
303
304=head1 Misc
305
306=head2 my $version = Compress::Raw::Bzip2::bzlibversion();
307
308Returns the version of the underlying bzip2 library.
309
310=head1 Constants
311
312The following bzip2 constants are exported by this module
313
314		BZ_RUN
315		BZ_FLUSH
316		BZ_FINISH
317
318		BZ_OK
319		BZ_RUN_OK
320		BZ_FLUSH_OK
321		BZ_FINISH_OK
322		BZ_STREAM_END
323		BZ_SEQUENCE_ERROR
324		BZ_PARAM_ERROR
325		BZ_MEM_ERROR
326		BZ_DATA_ERROR
327		BZ_DATA_ERROR_MAGIC
328		BZ_IO_ERROR
329		BZ_UNEXPECTED_EOF
330		BZ_OUTBUFF_FULL
331		BZ_CONFIG_ERROR
332
333=head1 SEE ALSO
334
335L<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>
336
337L<Compress::Zlib::FAQ|Compress::Zlib::FAQ>
338
339L<File::GlobMapper|File::GlobMapper>, L<Archive::Zip|Archive::Zip>,
340L<Archive::Tar|Archive::Tar>,
341L<IO::Zlib|IO::Zlib>
342
343The primary site for the bzip2 program is F<http://www.bzip.org>.
344
345See the module L<Compress::Bzip2|Compress::Bzip2>
346
347=head1 AUTHOR
348
349This module was written by Paul Marquess, F<pmqs@cpan.org>.
350
351=head1 MODIFICATION HISTORY
352
353See the Changes file.
354
355=head1 COPYRIGHT AND LICENSE
356
357Copyright (c) 2005-2010 Paul Marquess. All rights reserved.
358
359This program is free software; you can redistribute it and/or
360modify it under the same terms as Perl itself.
361
362