This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Update Compress-Raw-Bzip2 to CPAN version 2.033
[perl5.git] / cpan / Compress-Raw-Bzip2 / lib / Compress / Raw / Bzip2.pm
1
2 package Compress::Raw::Bzip2;
3
4 use strict ;
5 use warnings ;
6
7 require 5.004 ;
8 require Exporter;
9 use AutoLoader;
10 use Carp ;
11
12 use bytes ;
13 our ($VERSION, $XS_VERSION, @ISA, @EXPORT, $AUTOLOAD);
14
15 $VERSION = '2.033';
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
45 sub 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
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 ;
60
61 eval {
62     require XSLoader;
63     XSLoader::load('Compress::Raw::Bzip2', $XS_VERSION);
64     1;
65
66 or 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
94 package Compress::Raw::Bzip2;
95
96 1;
97
98 __END__
99
100
101 =head1 NAME
102
103 Compress::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
125 C<Compress::Raw::Bzip2> provides an interface to the in-memory
126 compression/uncompression functions from the bzip2 compression library. 
127
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
131 tasks.
132
133 =head1 Compression
134
135 =head2 ($z, $status) = new Compress::Raw::Bzip2 $appendOutput, $blockSize100k, $workfactor;
136
137 Creates a new compression object. 
138
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.
142
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.
145
146 Below is a list of the valid options:
147
148 =over 5
149
150 =item B<$appendOutput>
151
152 Controls whether the compressed data is appended to the output buffer in
153 the C<bzdeflate>, C<bzflush> and C<bzclose> methods.
154
155 Defaults to 1.
156
157 =item B<$blockSize100k>
158
159 To 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
166 Defaults to 1.
167
168 =item B<$workfactor>
169
170 To 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
191 Defaults to 0.
192
193 =back
194
195 =head2 $status = $bz->bzdeflate($input, $output);
196
197 Reads the contents of C<$input>, compresses it and writes the compressed
198 data to C<$output>.
199
200 Returns C<BZ_RUN_OK> on success and a C<bzip2> error code on failure.
201
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.
205
206 =head2 $status = $bz->bzflush($output);
207
208 Flushes any pending compressed data to C<$output>.
209
210 Returns C<BZ_RUN_OK> on success and a C<bzip2> error code on failure.
211
212 =head2 $status = $bz->bzclose($output);
213
214 Terminates the compressed data stream and flushes any pending compressed
215 data to C<$output>.
216
217 Returns 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
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.
228
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.
231
232 Below is a list of the valid options:
233
234 =over 5
235
236 =item B<$appendOutput>
237
238 Controls whether the compressed data is appended to the output buffer in the
239 C<bzinflate>, C<bzflush> and C<bzclose> methods.
240
241 Defaults to 1.
242
243 =item B<$consumeInput>
244
245 =item B<$small>
246
247 To 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
254 Defaults to 0.
255
256 =item B<$limitOutput>
257
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
260 limited. 
261
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.
266
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.
270
271 If C<LimitOutput> is enabled, the C<ConsumeInput> option will also be
272 enabled.
273
274 This option defaults to false.
275
276 =item B<$verbosity>
277
278 This parameter is ignored.
279
280 Defaults to 0.
281
282 =back
283
284 =head2 $status = $z->bzinflate($input, $output);
285
286 Uncompresses C<$input> and writes the uncompressed data to C<$output>. 
287
288 Returns C<BZ_OK> if the uncompression was successful, but the end of the
289 compressed data stream has not been reached. Returns C<BZ_STREAM_END> on
290 successful uncompression and the end of the compression stream has been
291 reached.
292
293 If C<consumeInput> is enabled in the constructor for the bunzip2 object,
294 C<$input> will have all compressed data removed from it after
295 uncompression. On C<BZ_OK> return this will mean that C<$input> will be an
296 empty string; when C<BZ_STREAM_END> C<$input> will either be an empty
297 string or will contain whatever data immediately followed the compressed
298 data stream.
299
300 If C<appendOutput> is enabled in the constructor for the bunzip2 object,
301 the uncompressed data will be appended to C<$output>. If not enabled,
302 C<$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
308 Returns the version of the underlying bzip2 library.
309
310 =head1 Constants
311
312 The 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
335 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>
336
337 L<Compress::Zlib::FAQ|Compress::Zlib::FAQ>
338
339 L<File::GlobMapper|File::GlobMapper>, L<Archive::Zip|Archive::Zip>,
340 L<Archive::Tar|Archive::Tar>,
341 L<IO::Zlib|IO::Zlib>
342
343 The primary site for the bzip2 program is F<http://www.bzip.org>.
344
345 See the module L<Compress::Bzip2|Compress::Bzip2>
346
347 =head1 AUTHOR
348
349 This module was written by Paul Marquess, F<pmqs@cpan.org>. 
350
351 =head1 MODIFICATION HISTORY
352
353 See the Changes file.
354
355 =head1 COPYRIGHT AND LICENSE
356
357 Copyright (c) 2005-2011 Paul Marquess. All rights reserved.
358
359 This program is free software; you can redistribute it and/or
360 modify it under the same terms as Perl itself.
361