ext/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.020';
  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, $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 =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
 298 =head1 Misc
 299
 300 =head2 my $version = Compress::Raw::Bzip2::bzlibversion();
 301
 302 Returns the version of the underlying bzip2 library.
 303
 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
 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::Lzop>, L<IO::Uncompress::UnLzop>, L<IO::Compress::Lzf>, L<IO::Uncompress::UnLzf>, L<IO::Uncompress::AnyInflate>, L<IO::Uncompress::AnyUncompress>
 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
 351 Copyright (c) 2005-2009 Paul Marquess. All rights reserved.
 352
 353 This program is free software; you can redistribute it and/or
 354 modify it under the same terms as Perl itself.
 355