This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Update Unicode-Collate to CPAN version 1.01
[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.006 ;
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.062';
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 sub Compress::Raw::Bzip2::STORABLE_freeze
95 {
96     my $type = ref shift;
97     croak "Cannot freeze $type object\n";
98 }
99
100 sub Compress::Raw::Bzip2::STORABLE_thaw
101 {
102     my $type = ref shift;
103     croak "Cannot thaw $type object\n";
104 }
105
106 sub Compress::Raw::Bunzip2::STORABLE_freeze
107 {
108     my $type = ref shift;
109     croak "Cannot freeze $type object\n";
110 }
111
112 sub Compress::Raw::Bunzip2::STORABLE_thaw
113 {
114     my $type = ref shift;
115     croak "Cannot thaw $type object\n";
116 }
117
118
119 package Compress::Raw::Bzip2;
120
121 1;
122
123 __END__
124
125
126 =head1 NAME
127
128 Compress::Raw::Bzip2 - Low-Level Interface to bzip2 compression library
129
130 =head1 SYNOPSIS
131
132     use Compress::Raw::Bzip2 ;
133
134     my ($bz, $status) = new Compress::Raw::Bzip2 [OPTS]
135         or die "Cannot create bzip2 object: $bzerno\n";
136     
137     $status = $bz->bzdeflate($input, $output);
138     $status = $bz->bzflush($output);
139     $status = $bz->bzclose($output);
140
141     my ($bz, $status) = new Compress::Raw::Bunzip2 [OPTS]
142         or die "Cannot create bunzip2 object: $bzerno\n";
143     
144     $status = $bz->bzinflate($input, $output);
145
146     my $version = Compress::Raw::Bzip2::bzlibversion();
147
148 =head1 DESCRIPTION
149
150 C<Compress::Raw::Bzip2> provides an interface to the in-memory
151 compression/uncompression functions from the bzip2 compression library. 
152
153 Although the primary purpose for the existence of C<Compress::Raw::Bzip2>
154 is for use by the  C<IO::Compress::Bzip2> and C<IO::Compress::Bunzip2>
155 modules, it can be used on its own for simple compression/uncompression
156 tasks.
157
158 =head1 Compression
159
160 =head2 ($z, $status) = new Compress::Raw::Bzip2 $appendOutput, $blockSize100k, $workfactor;
161
162 Creates a new compression object. 
163
164 If successful, it will return the initialised compression object, C<$z>
165 and a C<$status> of C<BZ_OK> in a list context. In scalar context it
166 returns the deflation object, C<$z>, only.
167
168 If not successful, the returned compression object, C<$z>, will be
169 I<undef> and C<$status> will hold the a I<bzip2> error code.
170
171 Below is a list of the valid options:
172
173 =over 5
174
175 =item B<$appendOutput>
176
177 Controls whether the compressed data is appended to the output buffer in
178 the C<bzdeflate>, C<bzflush> and C<bzclose> methods.
179
180 Defaults to 1.
181
182 =item B<$blockSize100k>
183
184 To quote the bzip2 documentation
185
186     blockSize100k specifies the block size to be used for compression. It
187     should be a value between 1 and 9 inclusive, and the actual block size
188     used is 100000 x this figure. 9 gives the best compression but takes
189     most memory.
190
191 Defaults to 1.
192
193 =item B<$workfactor>
194
195 To quote the bzip2 documentation
196
197     This parameter controls how the compression phase behaves when
198     presented with worst case, highly repetitive, input data. If
199     compression runs into difficulties caused by repetitive data, the
200     library switches from the standard sorting algorithm to a fallback
201     algorithm. The fallback is slower than the standard algorithm by
202     perhaps a factor of three, but always behaves reasonably, no matter how
203     bad the input.
204
205     Lower values of workFactor reduce the amount of effort the standard
206     algorithm will expend before resorting to the fallback. You should set
207     this parameter carefully; too low, and many inputs will be handled by
208     the fallback algorithm and so compress rather slowly, too high, and
209     your average-to-worst case compression times can become very large. The
210     default value of 30 gives reasonable behaviour over a wide range of
211     circumstances.
212
213     Allowable values range from 0 to 250 inclusive. 0 is a special case,
214     equivalent to using the default value of 30.
215
216 Defaults to 0.
217
218 =back
219
220 =head2 $status = $bz->bzdeflate($input, $output);
221
222 Reads the contents of C<$input>, compresses it and writes the compressed
223 data to C<$output>.
224
225 Returns C<BZ_RUN_OK> on success and a C<bzip2> error code on failure.
226
227 If C<appendOutput> is enabled in the constructor for the bzip2 object, the
228 compressed data will be appended to C<$output>. If not enabled, C<$output>
229 will be truncated before the compressed data is written to it.
230
231 =head2 $status = $bz->bzflush($output);
232
233 Flushes any pending compressed data to C<$output>.
234
235 Returns C<BZ_RUN_OK> on success and a C<bzip2> error code on failure.
236
237 =head2 $status = $bz->bzclose($output);
238
239 Terminates the compressed data stream and flushes any pending compressed
240 data to C<$output>.
241
242 Returns C<BZ_STREAM_END> on success and a C<bzip2> error code on failure.
243
244 =head2 Example
245
246 =head1 Uncompression
247
248 =head2 ($z, $status) = new Compress::Raw::Bunzip2 $appendOutput, $consumeInput, $small, $verbosity, $limitOutput;
249
250 If successful, it will return the initialised uncompression object, C<$z>
251 and a C<$status> of C<BZ_OK> in a list context. In scalar context it
252 returns the deflation object, C<$z>, only.
253
254 If not successful, the returned uncompression object, C<$z>, will be
255 I<undef> and C<$status> will hold the a I<bzip2> error code.
256
257 Below is a list of the valid options:
258
259 =over 5
260
261 =item B<$appendOutput>
262
263 Controls whether the compressed data is appended to the output buffer in the
264 C<bzinflate>, C<bzflush> and C<bzclose> methods.
265
266 Defaults to 1.
267
268 =item B<$consumeInput>
269
270 =item B<$small>
271
272 To quote the bzip2 documentation
273
274     If small is nonzero, the library will use an alternative decompression
275     algorithm which uses less memory but at the cost of decompressing more
276     slowly (roughly speaking, half the speed, but the maximum memory
277     requirement drops to around 2300k). 
278
279 Defaults to 0.
280
281 =item B<$limitOutput>
282
283 The C<LimitOutput> option changes the behavior of the C<< $i->bzinflate >>
284 method so that the amount of memory used by the output buffer can be
285 limited. 
286
287 When C<LimitOutput> is used the size of the output buffer used will either
288 be the 16k or the amount of memory already allocated to C<$output>,
289 whichever is larger. Predicting the output size available is tricky, so
290 don't rely on getting an exact output buffer size.
291
292 When C<LimitOutout> is not specified C<< $i->bzinflate >> will use as much
293 memory as it takes to write all the uncompressed data it creates by
294 uncompressing the input buffer.
295
296 If C<LimitOutput> is enabled, the C<ConsumeInput> option will also be
297 enabled.
298
299 This option defaults to false.
300
301 =item B<$verbosity>
302
303 This parameter is ignored.
304
305 Defaults to 0.
306
307 =back
308
309 =head2 $status = $z->bzinflate($input, $output);
310
311 Uncompresses C<$input> and writes the uncompressed data to C<$output>. 
312
313 Returns C<BZ_OK> if the uncompression was successful, but the end of the
314 compressed data stream has not been reached. Returns C<BZ_STREAM_END> on
315 successful uncompression and the end of the compression stream has been
316 reached.
317
318 If C<consumeInput> is enabled in the constructor for the bunzip2 object,
319 C<$input> will have all compressed data removed from it after
320 uncompression. On C<BZ_OK> return this will mean that C<$input> will be an
321 empty string; when C<BZ_STREAM_END> C<$input> will either be an empty
322 string or will contain whatever data immediately followed the compressed
323 data stream.
324
325 If C<appendOutput> is enabled in the constructor for the bunzip2 object,
326 the uncompressed data will be appended to C<$output>. If not enabled,
327 C<$output> will be truncated before the uncompressed data is written to it.
328
329 =head1 Misc
330
331 =head2 my $version = Compress::Raw::Bzip2::bzlibversion();
332
333 Returns the version of the underlying bzip2 library.
334
335 =head1 Constants
336
337 The following bzip2 constants are exported by this module
338
339                 BZ_RUN
340                 BZ_FLUSH
341                 BZ_FINISH
342
343                 BZ_OK
344                 BZ_RUN_OK
345                 BZ_FLUSH_OK
346                 BZ_FINISH_OK
347                 BZ_STREAM_END
348                 BZ_SEQUENCE_ERROR
349                 BZ_PARAM_ERROR
350                 BZ_MEM_ERROR
351                 BZ_DATA_ERROR
352                 BZ_DATA_ERROR_MAGIC
353                 BZ_IO_ERROR
354                 BZ_UNEXPECTED_EOF
355                 BZ_OUTBUFF_FULL
356                 BZ_CONFIG_ERROR
357
358 =head1 SEE ALSO
359
360 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>
361
362 L<IO::Compress::FAQ|IO::Compress::FAQ>
363
364 L<File::GlobMapper|File::GlobMapper>, L<Archive::Zip|Archive::Zip>,
365 L<Archive::Tar|Archive::Tar>,
366 L<IO::Zlib|IO::Zlib>
367
368 The primary site for the bzip2 program is F<http://www.bzip.org>.
369
370 See the module L<Compress::Bzip2|Compress::Bzip2>
371
372 =head1 AUTHOR
373
374 This module was written by Paul Marquess, F<pmqs@cpan.org>. 
375
376 =head1 MODIFICATION HISTORY
377
378 See the Changes file.
379
380 =head1 COPYRIGHT AND LICENSE
381
382 Copyright (c) 2005-2013 Paul Marquess. All rights reserved.
383
384 This program is free software; you can redistribute it and/or
385 modify it under the same terms as Perl itself.
386