| Commit | Line | Data |
|---|
| bdb7fd9f |
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 | |
| 9b5fd1d4 |
15 | $VERSION = '2.024'; |
| bdb7fd9f |
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 | |
| ea6efd2c |
223 | =head2 ($z, $status) = new Compress::Raw::Bunzip2 $appendOutput, $consumeInput, $small, $limitOutput; |
| bdb7fd9f |
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 | |
| ea6efd2c |
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 | |
| bdb7fd9f |
276 | =back |
| 277 | |
| 278 | =head2 $status = $z->bzinflate($input, $output); |
| 279 | |
| 280 | Uncompresses C<$input> and writes the uncompressed data to C<$output>. |
| 281 | |
| 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 |
| 285 | reached. |
| 286 | |
| 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 |
| 292 | data stream. |
| 293 | |
| 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. |
| 297 | |
| 319fab50 |
298 | =head1 Misc |
| 299 | |
| 300 | =head2 my $version = Compress::Raw::Bzip2::bzlibversion(); |
| 301 | |
| 302 | Returns the version of the underlying bzip2 library. |
| 303 | |
| bdb7fd9f |
304 | =head1 Constants |
| 305 | |
| 306 | The following bzip2 constants are exported by this module |
| 307 | |
| 308 | BZ_RUN |
| 309 | BZ_FLUSH |
| 310 | BZ_FINISH |
| 311 | |
| 312 | BZ_OK |
| 313 | BZ_RUN_OK |
| 314 | BZ_FLUSH_OK |
| 315 | BZ_FINISH_OK |
| 316 | BZ_STREAM_END |
| 317 | BZ_SEQUENCE_ERROR |
| 318 | BZ_PARAM_ERROR |
| 319 | BZ_MEM_ERROR |
| 320 | BZ_DATA_ERROR |
| 321 | BZ_DATA_ERROR_MAGIC |
| 322 | BZ_IO_ERROR |
| 323 | BZ_UNEXPECTED_EOF |
| 324 | BZ_OUTBUFF_FULL |
| 325 | BZ_CONFIG_ERROR |
| 326 | |
| 327 | =head1 SEE ALSO |
| 328 | |
| 9b5fd1d4 |
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> |
| bdb7fd9f |
330 | |
| 331 | L<Compress::Zlib::FAQ|Compress::Zlib::FAQ> |
| 332 | |
| 333 | L<File::GlobMapper|File::GlobMapper>, L<Archive::Zip|Archive::Zip>, |
| 334 | L<Archive::Tar|Archive::Tar>, |
| 335 | L<IO::Zlib|IO::Zlib> |
| 336 | |
| 337 | The primary site for the bzip2 program is F<http://www.bzip.org>. |
| 338 | |
| 339 | See the module L<Compress::Bzip2|Compress::Bzip2> |
| 340 | |
| 341 | =head1 AUTHOR |
| 342 | |
| 343 | This module was written by Paul Marquess, F<pmqs@cpan.org>. |
| 344 | |
| 345 | =head1 MODIFICATION HISTORY |
| 346 | |
| 347 | See the Changes file. |
| 348 | |
| 349 | =head1 COPYRIGHT AND LICENSE |
| 350 | |
| 9b5fd1d4 |
351 | Copyright (c) 2005-2010 Paul Marquess. All rights reserved. |
| bdb7fd9f |
352 | |
| 353 | This program is free software; you can redistribute it and/or |
| 354 | modify it under the same terms as Perl itself. |
| 355 | |
projects / p5sagit/p5-mst-13.2.git / blame