diff options
author | Norbert Preining <preining@logic.at> | 2010-05-12 16:54:37 +0000 |
---|---|---|
committer | Norbert Preining <preining@logic.at> | 2010-05-12 16:54:37 +0000 |
commit | 661c41a09e39a182865e0b51e34cc995a0dc96e8 (patch) | |
tree | 2f79bb1406e22fdcb2587be8ffda6c0c609d7932 /Master/tlpkg/tlperl/lib/Compress | |
parent | b645030efc22e13c2498a1522083634ab91b2de1 (diff) |
move tlperl.straw to tlperl
git-svn-id: svn://tug.org/texlive/trunk@18210 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/tlpkg/tlperl/lib/Compress')
-rwxr-xr-x | Master/tlpkg/tlperl/lib/Compress/Bzip2.pm | 1579 | ||||
-rwxr-xr-x | Master/tlpkg/tlperl/lib/Compress/Raw/Bzip2.pm | 355 | ||||
-rwxr-xr-x | Master/tlpkg/tlperl/lib/Compress/Raw/Zlib.pm | 1419 | ||||
-rwxr-xr-x | Master/tlpkg/tlperl/lib/Compress/Zlib.pm | 1494 | ||||
-rwxr-xr-x | Master/tlpkg/tlperl/lib/Compress/unLZMA.pm | 158 |
5 files changed, 5005 insertions, 0 deletions
diff --git a/Master/tlpkg/tlperl/lib/Compress/Bzip2.pm b/Master/tlpkg/tlperl/lib/Compress/Bzip2.pm new file mode 100755 index 00000000000..f7ffb0541a1 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Compress/Bzip2.pm @@ -0,0 +1,1579 @@ +# File : Bzip2.pm +# Author : Rob Janes +# Created : 14 April 2005 +# Modified : 9 Aug 2005 +# Version : 2.09 +# +# Copyright (c) 2005 Rob Janes. All rights reserved. +# This program is free software; you can redistribute it and/or +# modify it under the same terms as Perl itself. +# + +package Compress::Bzip2; + +use 5.006; + +use strict; +use warnings; + +use Carp; +use Getopt::Std; +use Fcntl qw(:DEFAULT :mode); + +require Exporter; +use AutoLoader; + +our @ISA = qw(Exporter); + +# Items to export into callers namespace by default. Note: do not export +# names by default without a very good reason. Use EXPORT_OK instead. +# Do not simply export all your public functions/methods/constants. + +# This allows declaration use Compress::Bzip2 ':all'; +# If you do not need this, moving things directly into @EXPORT or @EXPORT_OK +# will save memory. +our %EXPORT_TAGS = + ( 'constants' => [ qw( + BZ_CONFIG_ERROR + BZ_DATA_ERROR + BZ_DATA_ERROR_MAGIC + BZ_FINISH + BZ_FINISH_OK + BZ_FLUSH + BZ_FLUSH_OK + BZ_IO_ERROR + BZ_MAX_UNUSED + BZ_MEM_ERROR + BZ_OK + BZ_OUTBUFF_FULL + BZ_PARAM_ERROR + BZ_RUN + BZ_RUN_OK + BZ_SEQUENCE_ERROR + BZ_STREAM_END + BZ_UNEXPECTED_EOF + ) ], + + 'utilities' => [ qw( + &bzopen + &bzinflateInit + &bzdeflateInit + &memBzip &memBunzip + &compress &decompress + &bzip2 &bunzip2 + &bzlibversion + $bzerrno + ) ], + + 'bzip1' => [ qw( + &compress + &decompress + &compress_init + &decompress_init + &version + ) ], + + 'gzip' => [ qw( + &gzopen + &inflateInit + &deflateInit + &compress &uncompress + &adler32 &crc32 + + ZLIB_VERSION + + $gzerrno + + Z_OK + Z_STREAM_END + Z_NEED_DICT + Z_ERRNO + Z_STREAM_ERROR + Z_DATA_ERROR + Z_MEM_ERROR + Z_BUF_ERROR + Z_VERSION_ERROR + + Z_NO_FLUSH + Z_PARTIAL_FLUSH + Z_SYNC_FLUSH + Z_FULL_FLUSH + Z_FINISH + Z_BLOCK + + Z_NO_COMPRESSION + Z_BEST_SPEED + Z_BEST_COMPRESSION + Z_DEFAULT_COMPRESSION + + Z_FILTERED + Z_HUFFMAN_ONLY + Z_RLE + Z_DEFAULT_STRATEGY + + Z_BINARY + Z_ASCII + Z_UNKNOWN + + Z_DEFLATED + Z_NULL + ) ], + ); + +our @EXPORT_OK = ( @{ $EXPORT_TAGS{'utilities'} }, + @{ $EXPORT_TAGS{'constants'} }, + @{ $EXPORT_TAGS{'bzip1'} }, + @{ $EXPORT_TAGS{'gzip'} }, + ); + +$EXPORT_TAGS{'all'} = [ @EXPORT_OK ]; + +our @EXPORT = ( @{ $EXPORT_TAGS{'utilities'} }, @{ $EXPORT_TAGS{'constants'} } ); + +our $VERSION = "2.09"; + +our $bzerrno = ""; +our $gzerrno; +*gzerrno = \$bzerrno; + +# Zlib compatibility +## +use constant ZLIB_VERSION => '1.x'; +# allowed flush values +use constant { Z_NO_FLUSH => 0, Z_PARTIAL_FLUSH => 1, Z_SYNC_FLUSH => 2, + Z_FULL_FLUSH => 3, Z_FINISH => 4, Z_BLOCK => 5 }; +# return codes for functions, positive normal, negative error +use constant { Z_OK => 0, Z_STREAM_END => 1, Z_NEED_DICT => 2, Z_ERRNO => -1, + Z_STREAM_ERROR => -2, Z_DATA_ERROR => -3, Z_MEM_ERROR => -4, + Z_BUF_ERROR => -5, Z_VERSION_ERROR => -6 }; +# compression levels +use constant { Z_NO_COMPRESSION => 0, Z_BEST_SPEED => 1, + Z_BEST_COMPRESSION => 9, Z_DEFAULT_COMPRESSION => -1 }; +# compression strategy, for deflateInit +use constant { Z_FILTERED => 1, Z_HUFFMAN_ONLY => 2, Z_RLE => 3, + Z_DEFAULT_STRATEGY => 0 }; +# possible values of data_type (inflate) +use constant { Z_BINARY => 0, Z_ASCII => 1, Z_UNKNOWN => 2 }; +# the deflate compression method +use constant Z_DEFLATED => 8; +# for initialization +use constant Z_NULL => 0; + +## gzopen, $gzerror, gzerror, gzclose, gzreadline, gzwrite + +sub AUTOLOAD { + # This AUTOLOAD is used to 'autoload' constants from the constant() + # XS function. + + my $constname; + our $AUTOLOAD; + ($constname = $AUTOLOAD) =~ s/.*:://; + croak "&Compress::Bzip2::constant not defined" if $constname eq 'constant'; + my ($error, $val) = constant($constname); + if ($error) { croak $error; } + { + no strict 'refs'; + # Fixed between 5.005_53 and 5.005_61 +#XXX if ($] >= 5.00561) { +#XXX *$AUTOLOAD = sub () { $val }; +#XXX } +#XXX else { + *$AUTOLOAD = sub { $val }; +#XXX } + } + goto &$AUTOLOAD; +} + +require XSLoader; +XSLoader::load('Compress::Bzip2', $VERSION); + +#bootstrap Compress::Bzip2 $VERSION; + +############################################################################## +## file compress uncompress commands + +sub _writefileopen ( $$;$ ) { + ## open a protected file for write + my ( $handle, $filename, $force ) = @_; + + if ( sysopen($handle, $filename, $force ? O_WRONLY|O_CREAT|O_TRUNC : O_WRONLY|O_CREAT|O_EXCL, S_IWUSR|S_IRUSR) ) { + $_[0] = $handle if !defined($_[0]); + return $handle; + } + + return undef; +} + +sub _stat_snapshot ( $ ) { + my ( $filename ) = @_; + return undef if !defined($filename); + + my @stats = stat $filename; + if (!@stats) { + warn "stat of $filename failed: $!\n" if !@stats; + return undef; + } + + return \@stats; +} + +sub _check_stat ( $$;$ ) { + my ( $filename, $statsnap, $force ) = @_; + + if ( !defined($statsnap) || (ref($statsnap) eq 'ARRAY' && @$statsnap == 0) ) { + $statsnap = _stat_snapshot( $filename ); + if ( $statsnap ) { + if ( @_>1 ) { + if ( !defined($_[1]) ) { + $_[1] = $statsnap; + } + elsif ( ref($_[1]) eq 'ARRAY' && @{ $_[1] } == 0 ) { + @{ $_[1] } = @$statsnap; + } + } + } + else { + return undef; + } + } + + if ( S_ISDIR( $statsnap->[2] ) ) { + bz_seterror( &BZ_IO_ERROR, "file $filename is a directory" ); + return 0; + } + + if ( !S_ISREG( $statsnap->[2] ) ) { + bz_seterror( &BZ_IO_ERROR, "file $filename is not a normal file" ); + return 0; + } + + if ( !$force && S_ISLNK( $statsnap->[2] ) ) { + bz_seterror( &BZ_IO_ERROR, "file $filename is a symlink" ); + return 0; + } + + if ( !$force && $statsnap->[3] > 1 ) { + bz_seterror( &BZ_IO_ERROR, "file $filename has too many hard links" ); + return 0; + } + + return 1; +} + +sub _set_stat_from_snapshot ( $$ ) { + my ( $filename, $statsnap ) = @_; + + if ( !chmod( S_IMODE( $statsnap->[2] ), $filename ) ) { + bz_seterror( &BZ_IO_ERROR, "chmod ".sprintf('%03o', S_IMODE( $statsnap->[2] ))." $filename failed: $!" ); + return undef; + } + + if ( !utime @$statsnap[8,9], $filename ) { + bz_seterror( &BZ_IO_ERROR, + "utime " . join(' ',map { strftime('%Y-%m-%d %H:%M:%S', localtime $_) } @$statsnap[8,9] ) . + " $filename failed: $!" ); + return undef; + } + + if ( !chown @$statsnap[4,5], $filename ) { + bz_seterror( &BZ_IO_ERROR, + "chown " . join(':', ( getpwuid($statsnap->[4]) )[0], ( getgrgid($statsnap->[5]) )[0]) . + " $filename failed: $!" ); + return 0; + } + + return 1; +} + +sub bzip2 ( @ ) { + return _process_files( 'bzip2', 'cfvks123456789', @_ ); +} + +sub bunzip2 ( @ ) { + return _process_files( 'bunzip2', 'cdzfks123456789', @_ ); +} + +sub bzcat ( @ ) { + return _process_files( 'bzcat', 'cdzfks123456789', @_ ); +} + +sub _process_files ( @ ) { + my $command = shift; + my $opts = shift; + + local @ARGV = @_; + + my %opts; + return undef if !getopt( $opts, \%opts ); + # c compress or decompress to stdout + # d decompress + # z compress + # f force + # v verbose + # k keep + # s small + # 123456789 + + $opts{c} = 1 if $command eq 'bzcat'; + $opts{d} = 1 if $command eq 'bunzip2' || $command eq 'bzcat'; + $opts{z} = 1 if $command eq 'bzip2'; + + my $read_from_stdin; + my ( $in, $bzin ); + my ( $out, $bzout ); + + if ( !@ARGV ) { + $read_from_stdin = 1; + $opts{c} = 1; + if ( !open( $in, "<&STDIN" ) ) { + die "Error: failed to input from STDIN: '$!'\n"; + } + + $bzin = bzopen( $in, "r" ); + } + + if ( $opts{c} ) { + if ( !open( $out, ">&STDOUT" ) ) { + die "Error: failed to output to STDOUT: '$!'\n"; + } + + $bzout = bzopen( $out, "w" ); + } + + if ( !$opts{d} && !$opts{z} ) { + die "Error: neither compress nor decompress was indicated.\n"; + } + + my $doneflag = 0; + while ( !$doneflag ) { + my $infile; + my $outfile; + my @statbuf; + + if ( !$read_from_stdin ) { + $infile = shift @ARGV; + if ( ! -r $infile ) { + print STDERR "Error: file $infile is not readable\n"; + next; + } + + @statbuf = stat _; + if ( !@statbuf ) { + print STDERR "Error: failed to stat $infile: '$!'\n"; + next; + } + + if ( !_check_stat( $infile, \@statbuf, $opts{f} ) ) { + print STDERR "Error: file $infile stat check fails: $bzerrno\n"; + next; + } + } + + my $outfile_exists; + if ( !$opts{c} ) { + undef $out; + if ( $opts{d} ) { + $outfile = $infile . '.bz2'; + } + elsif ( $opts{z} ) { + $outfile = $infile =~ /\.bz2$/ ? substr($infile,0,-4) : $infile.'.out'; + } + + $outfile_exists = -e $outfile; + if ( !_writefileopen( $out, $outfile, $opts{f} ) ) { + print STDERR "Error: failed to open $outfile for write: '$!'\n"; + next; + } + } + + if ( !$read_from_stdin ) { + undef $in; + if ( !open( $in, $infile ) ) { + print STDERR "Error: unable to open $infile: '$!'\n"; + unlink( $outfile ) if !$outfile_exists; + next; + } + } + + if ( $opts{d} ) { + $bzin = bzopen( $in, "r" ) if !$read_from_stdin; + + my $buf; + my $notdone = 1; + while ( $notdone ) { + my $ln = bzread( $in, $buf, 1024 ); + if ( $ln > 0 ) { + syswrite( $out, $buf, $ln ); + } + elsif ( $ln == 0 ) { + undef $notdone; + } + else { + } + } + + close($out); + + if ( !$read_from_stdin ) { + bzclose($in); + unlink( $infile ) if !$opts{k}; + _set_stat_from_snapshot( $outfile, \@statbuf ); + } + } + elsif ( $opts{z} ) { + $bzout = bzopen( $out, "w" ) if !$opts{c}; + + my $buf; + my $notdone = 1; + while ( $notdone ) { + my $ln = sysread( $in, $buf, 1024 ); + if ( $ln > 0 ) { + bzwrite( $bzout, $buf, $ln ); + } + elsif ( $ln == 0 ) { + undef $notdone; + } + else { + } + } + + close($in); + + if ( !$opts{c} ) { + bzclose($bzout); + unlink( $infile ) if !$opts{k}; + _set_stat_from_snapshot( $outfile, \@statbuf ); + } + } + } +} + +############################################################################## +############################################################################## +## compatibility with Compress::Bzip2 1.03 + +sub add ( $$ ) { + my ( $obj, $buffer ) = @_; + + my @res = $obj->is_write ? $obj->bzdeflate( $buffer ) : $obj->bzinflate( $buffer ); + + return $res[0]; +} + +sub finish ( $;$ ) { + my ( $obj, $buffer ) = @_; + my ( @res, $out ); + + if ( defined($buffer) ) { + @res = $obj->is_write ? $obj->bzdeflate( $buffer ) : $obj->bzinflate( $buffer ); + return undef if $res[1] != &BZ_OK; + + $out = $res[0]; + } + $out = '' if !defined($out); + + @res = $obj->bzclose; + return undef if $res[1] != &BZ_OK; + + return $out.$res[0]; +} + +sub input_size ( $ ) { + my ( $obj ) = @_; + return $obj->total_in; +} + +sub output_size ( $ ) { + my ( $obj ) = @_; + return $obj->total_out; +} + +sub version ( ) { + return bzlibversion(); +} + +sub error ( $ ) { + return $_[0]->bzerror; +} + +############################################################################## +############################################################################## +## THE Compress::Zlib compatibility section + +sub _bzerror2gzerror { + my ( $bz_error_num ) = @_; + my $gz_error_num = + $bz_error_num == &BZ_OK ? Z_OK : + $bz_error_num == &BZ_RUN_OK ? Z_OK : + $bz_error_num == &BZ_FLUSH_OK ? Z_STREAM_END : + $bz_error_num == &BZ_FINISH_OK ? Z_STREAM_END : + $bz_error_num == &BZ_STREAM_END ? Z_STREAM_END : + + $bz_error_num == &BZ_SEQUENCE_ERROR ? Z_VERSION_ERROR : + $bz_error_num == &BZ_PARAM_ERROR ? Z_ERRNO : + $bz_error_num == &BZ_MEM_ERROR ? Z_MEM_ERROR : + $bz_error_num == &BZ_DATA_ERROR ? Z_DATA_ERROR : + $bz_error_num == &BZ_DATA_ERROR_MAGIC ? Z_DATA_ERROR : + $bz_error_num == &BZ_IO_ERROR ? Z_ERRNO : + $bz_error_num == &BZ_UNEXPECTED_EOF ? Z_STREAM_ERROR : + $bz_error_num == &BZ_OUTBUFF_FULL ? Z_BUF_ERROR : + $bz_error_num == &BZ_CONFIG_ERROR ? Z_VERSION_ERROR : + Z_VERSION_ERROR + ; + + return $gz_error_num; +} + +sub gzopen ( $$ ) { + goto &bzopen; +} + +sub gzread ( $$;$ ) { + goto &bzread; +} + +sub gzreadline ( $$ ) { + goto &bzreadline; +} + +sub gzwrite ( $$ ) { + goto &bzwrite; +} + +sub gzflush ( $;$ ) { + my ( $obj, $flush ) = @_; + return Z_OK if $flush == Z_NO_FLUSH; + goto &bzflush; +} + +sub gzclose ( $ ) { + goto &bzclose; +} + +sub gzeof ( $ ) { + goto &bzeof; +} + +sub gzsetparams ( $$$ ) { + ## ignore params + my ( $obj, $level, $strategy ) = @_; + return Z_OK; +} + +sub gzerror ( $ ) { + goto &bzerror; +} + +sub deflateInit ( @ ) { + ## ignore all options: + ## -Level, -Method, -WindowBits, -MemLevel, -Strategy, -Dictionary, -Bufsize + + my @res = bzdeflateInit(); + return $res[0] if !wantarray; + + return ( $res[0], _bzerror2gzerror( $res[1] ) ); +} + +sub deflate ( $$ ) { + my ( $obj, $buffer ) = @_; + + my @res = $obj->bzdeflate( $buffer ); + + return $res[0] if !wantarray; + return ( $res[0], _bzerror2gzerror( $res[1] ) ); +} + +sub deflateParams ( $;@ ) { + ## ignore all options + return Z_OK; +} + +sub flush ( $;$ ) { + my ( $obj, $flush_type ) = @_; + + $flush_type = Z_FINISH if !defined($flush_type); + return Z_OK if $flush_type == Z_NO_FLUSH; + + my $bz_flush_type; + my @res; + + $bz_flush_type = + $flush_type == Z_PARTIAL_FLUSH || $flush_type == Z_SYNC_FLUSH ? &BZ_FLUSH : + $flush_type == Z_FULL_FLUSH ? &BZ_FINISH : + &BZ_FINISH; + + @res = $obj->bzflush( $bz_flush_type ); + + return $res[0] if !wantarray; + return ( $res[0], _bzerror2gzerror( $res[1] ) ); +} + +sub dict_adler ( $ ) { + return 1; # ??? +} + +sub msg ( $ ) { + my ( $obj ) = @_; + + return ''.($obj->bzerror).''; # stringify +} + +sub inflateInit ( @ ) { + ## ignore all options: + ## -WindowBits, -Dictionary, -Bufsize + + my @res = bzinflateInit(); + return $res[0] if !wantarray; + + return ( $res[0], _bzerror2gzerror( $res[1] ) ); +} + +sub inflate ( $$ ) { + my ( $obj, $buffer ) = @_; + + my @res = $obj->bzinflate( $buffer ); + + return $res[0] if !wantarray; + return ( $res[0], _bzerror2gzerror( $res[1] ) ); +} + +sub inflateSync ( $ ) { + return Z_VERSION_ERROR; # ?? what +} + +sub memGzip ( $ ) { + goto &memBzip; +} + +sub memGunzip ( $ ) { + goto &memBunzip; +} + +sub adler32 ( $;$ ) { + return 0; +} + +sub crc32 ( $;$ ) { + return 0; +} + +# sub compress ( $;$ ) { +# ## ignore $level +# my ( $source, $level ) = @_; +# return memBzip( $source ); +# } + +sub uncompress ( $ ) { + my ( $source, $level ) = @_; + return memBunzip( $source ); +} + +# Autoload methods go after =cut, and are processed by the autosplit program. + +1; + +__END__ + +=pod + +=head1 NAME + +Compress::Bzip2 - Interface to Bzip2 compression library + +=head1 SYNOPSIS + + use Compress::Bzip2 qw(:all :constant :utilities :gzip); + + ($bz, $status) = bzdeflateInit( [PARAMS] ) ; + ($out, $status) = $bz->bzdeflate($buffer) ; + + ($bz, $status) = bzinflateInit( [PARAMS] ) ; + ($out, $status) = $bz->bzinflate($buffer) ; + + ($out, $status) = $bz->bzflush() ; + ($out, $status) = $bz->bzclose() ; + + $dest = memBzip($source); + alias compress + $dest = memBunzip($source); + alias decompress + + $bz = Compress::Bzip2->new( [PARAMS] ); + + $bz = bzopen($filename or filehandle, $mode); + alternate, with $bz created by new(): + $bz->bzopen($filename or filehandle, $mode); + + $bytesread = $bz->bzread($buffer [,$size]) ; + $bytesread = $bz->bzreadline($line); + $byteswritten = $bz->bzwrite($buffer [,$limit]); + $errstring = $bz->bzerror(); + $status = $bz->bzeof(); + $status = $bz->bzflush(); + $status = $bz->bzclose() ; + + $status = $bz->bzsetparams( $param => $setting ); + + $bz->total_in() ; + $bz->total_out() ; + + $verstring = $bz->bzversion(); + + $Compress::Bzip2::bzerrno + +=head1 DESCRIPTION + +The I<Compress::Bzip2> module provides a Perl interface to the I<Bzip2> +compression library (see L</AUTHOR> for details about where to get +I<Bzip2>). A relevant subset of the functionality provided by I<Bzip2> +is available in I<Compress::Bzip2>. + +All string parameters can either be a scalar or a scalar reference. + +The module can be split into two general areas of functionality, namely +in-memory compression/decompression and read/write access to I<bzip2> +files. Each of these areas will be discussed separately below. + +=head1 FILE READ/WRITE INTERFACE + +A number of functions are supplied in I<bzlib> for reading and writing +I<bzip2> files. Unfortunately, most of them are not suitable. So, this +module provides another interface, built over top of the low level bzlib +methods. + +=over 5 + +=head2 B<$bz = bzopen(filename or filehandle, mode)> + +This function returns an object which is used to access the other +I<bzip2> methods. + +The B<mode> parameter is used to specify both whether the file is +opened for reading or writing, with "r" or "w" respectively. + +If a reference to an open filehandle is passed in place of the +filename, it better be positioned to the start of a +compression/decompression sequence. + +=head2 B<$bz = Compress::Bzip2-E<gt>new( [PARAMS] )> + +Create a Compress::Bzip2 object. Optionally, provide +compression/decompression parameters as a keyword => setting list. +See I<bzsetparams()> for a description of the parameters. + +=head2 B<$bz-E<gt>bzopen(filename or filehandle, mode)> + +This is bzopen, but it uses an object previously created by the new +method. Other than that, it is identical to the above bzopen. + +=head2 B<$bytesread = $bz-E<gt>bzread($buffer [, $size]) ;> + +Reads B<$size> bytes from the compressed file into B<$buffer>. If +B<$size> is not specified, it will default to 4096. If the scalar +B<$buffer> is not large enough, it will be extended automatically. + +Returns the number of bytes actually read. On EOF it returns 0 and in +the case of an error, -1. + +=head2 B<$bytesread = $bz-E<gt>bzreadline($line) ;> + +Reads the next line from the compressed file into B<$line>. + +Returns the number of bytes actually read. On EOF it returns 0 and in +the case of an error, -1. + +It IS legal to intermix calls to B<bzread> and B<bzreadline>. + +At this time B<bzreadline> ignores the variable C<$/> +(C<$INPUT_RECORD_SEPARATOR> or C<$RS> when C<English> is in use). The +end of a line is denoted by the C character C<'\n'>. + +=head2 B<$byteswritten = $bz-E<gt>bzwrite($buffer [, $limit]) ;> + +Writes the contents of B<$buffer> to the compressed file. Returns the +number of bytes actually written, or 0 on error. + +If $limit is given and non-zero, then only that many bytes from +$buffer will be written. + +=head2 B<$status = $bz-E<gt>bzflush($flush) ;> + +Flushes all pending output to the compressed file. +Works identically to the I<zlib> function it interfaces to. Note that +the use of B<bzflush> can degrade compression. + +Returns C<BZ_OK> if B<$flush> is C<BZ_FINISH> and all output could be +flushed. Otherwise the bzlib error code is returned. + +Refer to the I<bzlib> documentation for the valid values of B<$flush>. + +=head2 B<$status = $bz-E<gt>bzeof() ;> + +Returns 1 if the end of file has been detected while reading the input +file, otherwise returns 0. + +=head2 B<$bz-E<gt>bzclose> + +Closes the compressed file. Any pending data is flushed to the file +before it is closed. + +=head2 B<$bz-E<gt>bzsetparams( [PARAMS] );> + +Change settings for the deflate stream C<$bz>. + +The list of the valid options is shown below. Options not specified +will remain unchanged. + +=over 5 + +=item B<-verbosity> + +Defines the verbosity level. Valid values are 0 through 4, + +The default is C<-verbosity =E<gt> 0>. + +=item B<-blockSize100k> + +For bzip object opened for stream deflation or write. + +Defines the buffering factor of compression method. The algorithm +buffers all data until the buffer is full, then it flushes all the +data out. Use -blockSize100k to specify the size of the buffer. + +Valid settings are 1 through 9, representing a blocking in multiples +of 100k. + +Note that each such block has an overhead of leading and trailing +synchronization bytes. bzip2 recovery uses this information to +pull useable data out of a corrupted file. + +A streaming application would probably want to set the blocking low. + +=item B<-workFactor> + +For bzip object opened for stream deflation or write. + +The workFactor setting tells the deflation algorithm how much work +to invest to compensate for repetitive data. + +workFactor may be a number from 0 to 250 inclusive. The default setting +is 30. + +See the bzip documentation for more information. + +=item B<-small> + +For bzip object opened for stream inflation or read. + +B<small> may be 0 or 1. Set C<small> to one to use a slower, less +memory intensive algorithm. + +=back + +=head2 B<$bz-E<gt>bzerror> + +Returns the I<bzlib> error message or number for the last operation +associated with B<$bz>. The return value will be the I<bzlib> error +number when used in a numeric context and the I<bzlib> error message +when used in a string context. The I<bzlib> error number constants, +shown below, are available for use. + + BZ_CONFIG_ERROR + BZ_DATA_ERROR + BZ_DATA_ERROR_MAGIC + BZ_FINISH + BZ_FINISH_OK + BZ_FLUSH + BZ_FLUSH_OK + BZ_IO_ERROR + BZ_MAX_UNUSED + BZ_MEM_ERROR + BZ_OK + BZ_OUTBUFF_FULL + BZ_PARAM_ERROR + BZ_RUN + BZ_RUN_OK + BZ_SEQUENCE_ERROR + BZ_STREAM_END + BZ_UNEXPECTED_EOF + +=head2 B<$bzerrno> + +The B<$bzerrno> scalar holds the error code associated with the most +recent I<bzip2> routine. Note that unlike B<bzerror()>, the error is +I<not> associated with a particular file. + +As with B<bzerror()> it returns an error number in numeric context and +an error message in string context. Unlike B<bzerror()> though, the +error message will correspond to the I<bzlib> message when the error is +associated with I<bzlib> itself, or the UNIX error message when it is +not (i.e. I<bzlib> returned C<Z_ERRORNO>). + +As there is an overlap between the error numbers used by I<bzlib> and +UNIX, B<$bzerrno> should only be used to check for the presence of +I<an> error in numeric context. Use B<bzerror()> to check for specific +I<bzlib> errors. The I<bzcat> example below shows how the variable can +be used safely. + +=back + +=head1 Compress::Bzip2 1.03 COMPATIBILITY + +While the 2.x thread forked off of 1.00, another line of development +came to a head at 1.03. The 1.03 version worked with bzlib 1.0.2, had +improvements to the error handling, single buffer inflate/deflate, a +streaming interface to inflate/deflate, and a cpan style test suite. + +=over 5 + +=head2 B<$dest = compress( $string, [$level] )> + +Alias to memBzip, this compresses string, using the optional +compression level, 1 through 9, the default being 1. Returns a string +containing the compressed data. + +On error I<undef> is returned. + +=head2 B<$dest = decompress($string)> + +Alias to memBunzip, this decompresses the data in string, returning a +string containing the decompressed data. + +On error I<undef> is returned. + +=head2 B<$stream = compress_init( [PARAMS] )> + +Alias to bzdeflateInit. In addition to the named parameters +documented for bzdeflateInit, the following are accepted: + + -level, alias to -blockSize100k + -buffer, to set the buffer size. + +The -buffer option is ignored. The intermediate buffer size is not +changeable. + +=head2 B<$stream = decompress_init( [PARAMS] )> + +Alias to bzinflateInit. See bzinflateInit for a description of the parameters. +The option "-buffer" is accepted, but ignored. + +=head2 B<$output = $stream-E<gt>add( $string )> + +Add data to be compressed/decompressed. Returns whatever output is available +(possibly none, if it's still buffering it), or undef on error. + +=head2 B<$output = $stream-E<gt>finish( [$string] )> + +Finish the operation; takes an optional final data string. Whatever is +returned completes the output; returns undef on error. + +=head2 B<$stream-E<gt>error> + +Like the function, but applies to the current object only. Note that errors +in a stream object are also returned by the function. + +=head2 B<$stream-E<gt>input_size> + +Alias to total_in. Total bytes passed to the stream. + +=head2 B<$stream-E<gt>output_size> + +Alias to total_out. Total bytes received from the stream. + +=back + +=head1 GZIP COMPATIBILITY INTERFACE + +Except for the exact state and error numbers, this package presents an +interface very much like that given by the Compress::Zlib package. +Mostly, if you take the method name, state or error number from +Compress::Zlib and replace the "g" with a "b", your code should work. + +To make the interoperability even easier, all the Compress::Zlib method +names have been used as aliases or cover functions for the bzip2 methods. + +Therefore, most code that uses Compress::Zlib should be able to use +this package, with a one line change. + +Simply change + + $gz = Compress::Zlib::gzopen( "filename", "w" ); + +to + + $gz = Compress::Bzip2::gzopen( "filename", "w" ); + +Some of the Compress::Zlib aliases don't return anything useful, like +crc32 or adler32, cause bzip2 doesn't do that sort of thing. + +=over 5 + +=head2 B< $gz = gzopen( $filename, $mode ) > + +Alias for bzopen. + +=head2 B< $gz-E<gt>gzread( $buffer, [ $length ] ) > + +Alias for bzread. + +=head2 B< $gz-E<gt>gzreadline( $buffer ) > + +Alias for bzreadline. + +=head2 B< $gz-E<gt>gzwrite( $buffer ) > + +Alias for bzwrite. + +=head2 B< $gz-E<gt>gzflush( [$flushtype] ) > + +Alias for bzflush, with return code translation. + +=head2 B< $gz-E<gt>gzclose( ) > + +Alias for bzclose. + +=head2 B< $gz-E<gt>gzeof( ) > + +Alias for bzeof. + +=head2 B< $gz-E<gt>gzerror( ) > + +Alias for bzerror. + +=head2 B< $gz-E<gt>gzsetparams( $level, $strategy ) > + +This is a no-op. + +=head2 B< $d = deflateInit( [OPTS] ) > + +Alias for bzdeflateInit, with return code translation. + +All OPTS are ignored. + +=head2 B< $d-E<gt>deflate( $buffer ) > + +Alias for bzdeflate, with return code translation. + +=head2 B< $d-E<gt>deflateParams( [OPTS] ) > + +This is a no-op. + +=head2 B< $d-E<gt>flush( [$flushtype] ) > + +Cover function for bzflush or bzclose, depending on $flushtype. + +See the Compress::Zlib documentation for more information. + +=head2 B< $d-E<gt>dict_adler( ) > + +This is a no-op. + +=head2 B< $d-E<gt>msg( ) > + +This is a no-op. + +=head2 B< $d = inflateInit( [OPTS] ) > + +Alias for bzinflateInit, with return code translation. + +All OPTS are ignored. + +=head2 B< $d-E<gt>inflate( ) > + +Alias for bzinflate, with return code translation. + +=head2 B< $d-E<gt>inflateSync( ) > + +This is a no-op. + +=head2 B< $d-E<gt>adler32( $crc ) > + +This is a no-op. + +=head2 B< $d-E<gt>crc32( $crc ) > + +This is a no-op. + +=head2 B< $buffer = memGzip( $buffer ) > + +Alias for memBzip. + +=head2 B< $buffer = memGunzip( $buffer ) > + +Alias for memBunzip. + +=back + +=head1 IN-MEMORY COMPRESS/UNCOMPRESS + +Two high-level functions are provided by I<bzlib> to perform in-memory +compression. They are B<memBzip> and B<memBunzip>. Two Perl subs are +provided which provide similar functionality. + +=over 5 + +=head2 B<$compressed = memBzip($buffer);> + +Compresses B<$source>. If successful it returns the compressed +data. Otherwise it returns I<undef>. + +The buffer parameter can either be a scalar or a scalar reference. + +Essentially, an in-memory bzip file is created. It creates a minimal +bzip header. + +=head2 B<$uncompressed = memBunzip($buffer);> + +Uncompresses B<$source>. If successful it returns the uncompressed +data. Otherwise it returns I<undef>. + +The source buffer can either be a scalar or a scalar reference. + +The buffer parameter can either be a scalar or a scalar reference. The +contents of the buffer parameter are destroyed after calling this +function. + +=back + +=head1 STREAM DEFLATE + +The Perl interface will I<always> consume the complete input buffer +before returning. Also the output buffer returned will be +automatically grown to fit the amount of output available. + +Here is a definition of the interface available: + +=head2 B<($d, $status) = bzdeflateInit( [PARAMS] )> + +Initialises a deflation stream. + +If successful, it will return the initialised deflation stream, B<$d> +and B<$status> of C<BZ_OK> in a list context. In scalar context it +returns the deflation stream, B<$d>, only. + +If not successful, the returned deflation stream (B<$d>) will be +I<undef> and B<$status> will hold the exact I<bzip2> error code. + +The function optionally takes a number of named options specified as +C<-Name=E<gt>value> pairs. This allows individual options to be +tailored without having to specify them all in the parameter list. + +Here is a list of the valid options: + +=over 5 + +=item B<-verbosity> + +Defines the verbosity level. Valid values are 0 through 4, + +The default is C<-verbosity =E<gt> 0>. + +=item B<-blockSize100k> + +Defines the buffering factor of compression method. The algorithm +buffers all data until the buffer is full, then it flushes all the +data out. Use -blockSize100k to specify the size of the buffer. + +Valid settings are 1 through 9, representing a blocking in multiples +of 100k. + +Note that each such block has an overhead of leading and trailing +synchronization bytes. bzip2 recovery uses this information to +pull useable data out of a corrupted file. + +A streaming application would probably want to set the blocking low. + +=item B<-workFactor> + +The workFactor setting tells the deflation algorithm how much work +to invest to compensate for repetitive data. + +workFactor may be a number from 0 to 250 inclusive. The default setting +is 30. + +See the bzip documentation for more information. + +=back + +Here is an example of using the B<deflateInit> optional parameter list +to override the default buffer size and compression level. All other +options will take their default values. + + bzdeflateInit( -blockSize100k => 1, -verbosity => 1 ); + +=head2 B<($out, $status) = $d-E<gt>bzdeflate($buffer)> + +Deflates the contents of B<$buffer>. The buffer can either be a scalar +or a scalar reference. When finished, B<$buffer> will be +completely processed (assuming there were no errors). If the deflation +was successful it returns deflated output, B<$out>, and a status +value, B<$status>, of C<Z_OK>. + +On error, B<$out> will be I<undef> and B<$status> will contain the +I<zlib> error code. + +In a scalar context B<bzdeflate> will return B<$out> only. + +As with the internal buffering of the I<deflate> function in I<bzip2>, +it is not necessarily the case that any output will be produced by +this method. So don't rely on the fact that B<$out> is empty for an +error test. In fact, given the size of bzdeflates internal buffer, +with most files it's likely you won't see any output at all until +flush or close. + +=head2 B<($out, $status) = $d-E<gt>bzflush([flush_type])> + +Typically used to finish the deflation. Any pending output will be +returned via B<$out>. B<$status> will have a value C<BZ_OK> if +successful. + +In a scalar context B<bzflush> will return B<$out> only. + +Note that flushing can seriously degrade the compression ratio, so it +should only be used to terminate a decompression (using C<BZ_FLUSH>) or +when you want to create a I<full flush point> (using C<BZ_FINISH>). + +The allowable values for C<flush_type> are C<BZ_FLUSH> and C<BZ_FINISH>. + +For a handle opened for "w" (bzwrite), the default is C<BZ_FLUSH>. +For a stream, the default for C<flush_type> is C<BZ_FINISH> (which is +essentially a close and reopen). + +It is strongly recommended that you only set the C<flush_type> +parameter if you fully understand the implications of what it +does. See the C<bzip2> documentation for details. + +=head2 Example + +Here is a trivial example of using B<bzdeflate>. It simply reads standard +input, deflates it and writes it to standard output. + + use strict ; + use warnings ; + + use Compress::Bzip2 ; + + binmode STDIN; + binmode STDOUT; + my $x = bzdeflateInit() + or die "Cannot create a deflation stream\n" ; + + my ($output, $status) ; + while (<>) + { + ($output, $status) = $x->bzdeflate($_) ; + + $status == BZ_OK + or die "deflation failed\n" ; + + print $output ; + } + + ($output, $status) = $x->bzclose() ; + + $status == BZ_OK + or die "deflation failed\n" ; + + print $output ; + +=head1 STREAM INFLATE + +Here is a definition of the interface: + +=head2 B<($i, $status) = inflateInit()> + +Initialises an inflation stream. + +In a list context it returns the inflation stream, B<$i>, and the +I<zlib> status code (B<$status>). In a scalar context it returns the +inflation stream only. + +If successful, B<$i> will hold the inflation stream and B<$status> will +be C<BZ_OK>. + +If not successful, B<$i> will be I<undef> and B<$status> will hold the +I<bzlib.h> error code. + +The function optionally takes a number of named options specified as +C<-Name=E<gt>value> pairs. This allows individual options to be +tailored without having to specify them all in the parameter list. + +For backward compatibility, it is also possible to pass the parameters +as a reference to a hash containing the name=>value pairs. + +The function takes one optional parameter, a reference to a hash. The +contents of the hash allow the deflation interface to be tailored. + +Here is a list of the valid options: + +=over 5 + +=item B<-small> + +B<small> may be 0 or 1. Set C<small> to one to use a slower, less +memory intensive algorithm. + +=item B<-verbosity> + +Defines the verbosity level. Valid values are 0 through 4, + +The default is C<-verbosity =E<gt> 0>. + +=back + +Here is an example of using the B<bzinflateInit> optional parameter. + + bzinflateInit( -small => 1, -verbosity => 1 ); + +=head2 B<($out, $status) = $i-E<gt>bzinflate($buffer)> + +Inflates the complete contents of B<$buffer>. The buffer can either be +a scalar or a scalar reference. + +Returns C<BZ_OK> if successful and C<BZ_STREAM_END> if the end of the +compressed data has been successfully reached. If not successful, +B<$out> will be I<undef> and B<$status> will hold the I<bzlib> error +code. + +The C<$buffer> parameter is modified by C<bzinflate>. On completion it +will contain what remains of the input buffer after inflation. This +means that C<$buffer> will be an empty string when the return status +is C<BZ_OK>. When the return status is C<BZ_STREAM_END> the C<$buffer> +parameter will contains what (if anything) was stored in the input +buffer after the deflated data stream. + +This feature is useful when processing a file format that encapsulates +a compressed data stream. + +=head2 Example + +Here is an example of using B<bzinflate>. + + use strict ; + use warnings ; + + use Compress::Bzip2; + + my $x = bzinflateInit() + or die "Cannot create a inflation stream\n" ; + + my $input = '' ; + binmode STDIN; + binmode STDOUT; + + my ($output, $status) ; + while (read(STDIN, $input, 4096)) + { + ($output, $status) = $x->bzinflate(\$input) ; + + print $output + if $status == BZ_OK or $status == BZ_STREAM_END ; + + last if $status != BZ_OK ; + } + + die "inflation failed\n" + unless $status == BZ_STREAM_END ; + +=head1 EXAMPLES + +Here are some example scripts of using the interface. + +=over 5 + +=head2 B<A bzcat function> + + use strict ; + use warnings ; + + use Compress::Bzip2 ; + + die "Usage: bzcat file...\n" unless @ARGV ; + + my $file ; + + foreach $file (@ARGV) { + my $buffer ; + + my $bz = bzopen($file, "rb") + or die "Cannot open $file: $bzerrno\n" ; + + print $buffer while $bz->bzread($buffer) > 0 ; + + die "Error reading from $file: $bzerrno" . ($bzerrno+0) . "\n" + if $bzerrno != BZ_STREAM_END ; + + $bz->bzclose() ; + } + +=head2 B<A grep using bzreadline> + + use strict ; + use warnings ; + + use Compress::Bzip2 ; + + die "Usage: bzgrep pattern file...\n" unless @ARGV >= 2; + + my $pattern = shift ; + + my $file ; + + foreach $file (@ARGV) { + my $bz = bzopen($file, "rb") + or die "Cannot open $file: $bzerrno\n" ; + + while ($bz->bzreadline($_) > 0) { + print if /$pattern/ ; + } + + die "Error reading from $file: $bzerrno\n" + if $bzerrno != Z_STREAM_END ; + + $bz->bzclose() ; + } + +=head2 B<Streaming Compression> + +This script, I<bzstream>, does the opposite of the I<bzcat> script +above. It reads from standard input and writes a bzip file to standard +output. + + use strict ; + use warnings ; + + use Compress::Bzip2 ; + + binmode STDOUT; # bzopen only sets it on the fd + + my $bz = bzopen(\*STDOUT, "wb") + or die "Cannot open stdout: $bzerrno\n" ; + + while (<>) { + $bz->bzwrite($_) or die "error writing: $bzerrno\n" ; + } + + $bz->bzclose ; + +=back + +=head1 EXPORT + +Use the tags :all, :utilities, :constants, :bzip1 and :gzip. + +=head2 Export tag :all + +This exports all the exportable methods. + +=head2 Export tag :constants + +This exports only the BZ_* constants. + +=head2 Export tag :bzip1 + +This exports the Compress::Bzip2 1.x functions, for compatibility. + + compress + decompress + compress_init + decompress_init + version + +These are actually aliases to memBzip and memBunzip. + +=head2 Export tag :utilities + +This gives an interface to the bzip2 methods. + + bzopen + bzinflateInit + bzdeflateInit + memBzip + memBunzip + bzip2 + bunzip2 + bzcat + bzlibversion + $bzerrno + +=head2 Export tag :gzip + +This gives compatibility with Compress::Zlib. + + gzopen + gzinflateInit + gzdeflateInit + memGzip + memGunzip + $gzerrno + +=head1 Exportable constants + +All the I<bzlib> constants are automatically imported when you make use +of I<Compress::Bzip2>. + + BZ_CONFIG_ERROR + BZ_DATA_ERROR + BZ_DATA_ERROR_MAGIC + BZ_FINISH + BZ_FINISH_OK + BZ_FLUSH + BZ_FLUSH_OK + BZ_IO_ERROR + BZ_MAX_UNUSED + BZ_MEM_ERROR + BZ_OK + BZ_OUTBUFF_FULL + BZ_PARAM_ERROR + BZ_RUN + BZ_RUN_OK + BZ_SEQUENCE_ERROR + BZ_STREAM_END + BZ_UNEXPECTED_EOF + +=head1 SEE ALSO + +The documentation for zlib, bzip2 and Compress::Zlib. + +=head1 AUTHOR + +Rob Janes, E<lt>arjay at cpan.orgE<gt> + +=head1 COPYRIGHT AND LICENSE + +Copyright (C) 2005 by Rob Janes + +This library is free software; you can redistribute it and/or modify +it under the same terms as Perl itself, either Perl version 5.8.3 or, +at your option, any later version of Perl 5 you may have available. + +=head1 AUTHOR + +The I<Compress::Bzip2> module was originally written by Gawdi Azem +F<azemgi@rupert.informatik.uni-stuttgart.de>. + +The first I<Compress::Bzip2> module was written by Gawdi Azem +F<azemgi@rupert.informatik.uni-stuttgart.de>. It provided an +interface to the in memory inflate and deflate routines. + +I<Compress::Bzip2> was subsequently passed on to Marco Carnut +F<kiko@tempest.com.br> who shepharded it through to version 1.03, a +set of changes which included upgrades to handle bzlib 1.0.2, and +improvements to the in memory inflate and deflate routines. The +streaming interface and error information were added by David Robins +F<dbrobins@davidrobins.net>. + +Version 2 of I<Compress::Bzip2> is due to Rob Janes, of +arjay@cpan.org. This release is intended to give an interface +close to that of Compress::Zlib. It's development forks from 1.00, +not 1.03, so the streaming interface is not the same as that in 1.03, +although apparently compatible as it passes the 1.03 test suite. + +=head1 MODIFICATION HISTORY + +See the Changes file. + +2.00 Second public release of I<Compress::Bzip2>. + + + diff --git a/Master/tlpkg/tlperl/lib/Compress/Raw/Bzip2.pm b/Master/tlpkg/tlperl/lib/Compress/Raw/Bzip2.pm new file mode 100755 index 00000000000..48f82073355 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Compress/Raw/Bzip2.pm @@ -0,0 +1,355 @@ + +package Compress::Raw::Bzip2; + +use strict ; +use warnings ; + +require 5.004 ; +require Exporter; +use AutoLoader; +use Carp ; + +use bytes ; +our ($VERSION, $XS_VERSION, @ISA, @EXPORT, $AUTOLOAD); + +$VERSION = '2.024'; +$XS_VERSION = $VERSION; +$VERSION = eval $VERSION; + +@ISA = qw(Exporter); +# Items to export into callers namespace by default. Note: do not export +# names by default without a very good reason. Use EXPORT_OK instead. +# Do not simply export all your public functions/methods/constants. +@EXPORT = qw( + BZ_RUN + BZ_FLUSH + BZ_FINISH + + BZ_OK + BZ_RUN_OK + BZ_FLUSH_OK + BZ_FINISH_OK + BZ_STREAM_END + BZ_SEQUENCE_ERROR + BZ_PARAM_ERROR + BZ_MEM_ERROR + BZ_DATA_ERROR + BZ_DATA_ERROR_MAGIC + BZ_IO_ERROR + BZ_UNEXPECTED_EOF + BZ_OUTBUFF_FULL + BZ_CONFIG_ERROR + + ); + +sub AUTOLOAD { + my($constname); + ($constname = $AUTOLOAD) =~ s/.*:://; + my ($error, $val) = constant($constname); + Carp::croak $error if $error; + no strict 'refs'; + *{$AUTOLOAD} = sub { $val }; + goto &{$AUTOLOAD}; + +} + +use constant FLAG_APPEND => 1 ; +use constant FLAG_CRC => 2 ; +use constant FLAG_ADLER => 4 ; +use constant FLAG_CONSUME_INPUT => 8 ; + +eval { + require XSLoader; + XSLoader::load('Compress::Raw::Bzip2', $XS_VERSION); + 1; +} +or do { + require DynaLoader; + local @ISA = qw(DynaLoader); + bootstrap Compress::Raw::Bzip2 $XS_VERSION ; +}; + +#sub Compress::Raw::Bzip2::new +#{ +# my $class = shift ; +# my ($ptr, $status) = _new(@_); +# return wantarray ? (undef, $status) : undef +# unless $ptr ; +# my $obj = bless [$ptr], $class ; +# return wantarray ? ($obj, $status) : $obj; +#} +# +#package Compress::Raw::Bunzip2 ; +# +#sub Compress::Raw::Bunzip2::new +#{ +# my $class = shift ; +# my ($ptr, $status) = _new(@_); +# return wantarray ? (undef, $status) : undef +# unless $ptr ; +# my $obj = bless [$ptr], $class ; +# return wantarray ? ($obj, $status) : $obj; +#} + +package Compress::Raw::Bzip2; + +1; + +__END__ + + +=head1 NAME + +Compress::Raw::Bzip2 - Low-Level Interface to bzip2 compression library + +=head1 SYNOPSIS + + use Compress::Raw::Bzip2 ; + + my ($bz, $status) = new Compress::Raw::Bzip2 [OPTS] + or die "Cannot create bzip2 object: $bzerno\n"; + + $status = $bz->bzdeflate($input, $output); + $status = $bz->bzflush($output); + $status = $bz->bzclose($output); + + my ($bz, $status) = new Compress::Raw::Bunzip2 [OPTS] + or die "Cannot create bunzip2 object: $bzerno\n"; + + $status = $bz->bzinflate($input, $output); + + my $version = Compress::Raw::Bzip2::bzlibversion(); + +=head1 DESCRIPTION + +C<Compress::Raw::Bzip2> provides an interface to the in-memory +compression/uncompression functions from the bzip2 compression library. + +Although the primary purpose for the existence of C<Compress::Raw::Bzip2> +is for use by the C<IO::Compress::Bzip2> and C<IO::Compress::Bunzip2> +modules, it can be used on its own for simple compression/uncompression +tasks. + +=head1 Compression + +=head2 ($z, $status) = new Compress::Raw::Bzip2 $appendOutput, $blockSize100k, $workfactor; + +Creates a new compression object. + +If successful, it will return the initialised compression object, C<$z> +and a C<$status> of C<BZ_OK> in a list context. In scalar context it +returns the deflation object, C<$z>, only. + +If not successful, the returned compression object, C<$z>, will be +I<undef> and C<$status> will hold the a I<bzip2> error code. + +Below is a list of the valid options: + +=over 5 + +=item B<$appendOutput> + +Controls whether the compressed data is appended to the output buffer in +the C<bzdeflate>, C<bzflush> and C<bzclose> methods. + +Defaults to 1. + +=item B<$blockSize100k> + +To quote the bzip2 documentation + + blockSize100k specifies the block size to be used for compression. It + should be a value between 1 and 9 inclusive, and the actual block size + used is 100000 x this figure. 9 gives the best compression but takes + most memory. + +Defaults to 1. + +=item B<$workfactor> + +To quote the bzip2 documentation + + This parameter controls how the compression phase behaves when + presented with worst case, highly repetitive, input data. If + compression runs into difficulties caused by repetitive data, the + library switches from the standard sorting algorithm to a fallback + algorithm. The fallback is slower than the standard algorithm by + perhaps a factor of three, but always behaves reasonably, no matter how + bad the input. + + Lower values of workFactor reduce the amount of effort the standard + algorithm will expend before resorting to the fallback. You should set + this parameter carefully; too low, and many inputs will be handled by + the fallback algorithm and so compress rather slowly, too high, and + your average-to-worst case compression times can become very large. The + default value of 30 gives reasonable behaviour over a wide range of + circumstances. + + Allowable values range from 0 to 250 inclusive. 0 is a special case, + equivalent to using the default value of 30. + +Defaults to 0. + +=back + +=head2 $status = $bz->bzdeflate($input, $output); + +Reads the contents of C<$input>, compresses it and writes the compressed +data to C<$output>. + +Returns C<BZ_RUN_OK> on success and a C<bzip2> error code on failure. + +If C<appendOutput> is enabled in the constructor for the bzip2 object, the +compressed data will be appended to C<$output>. If not enabled, C<$output> +will be truncated before the compressed data is written to it. + +=head2 $status = $bz->bzflush($output); + +Flushes any pending compressed data to C<$output>. + +Returns C<BZ_RUN_OK> on success and a C<bzip2> error code on failure. + +=head2 $status = $bz->bzclose($output); + +Terminates the compressed data stream and flushes any pending compressed +data to C<$output>. + +Returns C<BZ_STREAM_END> on success and a C<bzip2> error code on failure. + +=head2 Example + +=head1 Uncompression + +=head2 ($z, $status) = new Compress::Raw::Bunzip2 $appendOutput, $consumeInput, $small, $limitOutput; + +If successful, it will return the initialised uncompression object, C<$z> +and a C<$status> of C<BZ_OK> in a list context. In scalar context it +returns the deflation object, C<$z>, only. + +If not successful, the returned uncompression object, C<$z>, will be +I<undef> and C<$status> will hold the a I<bzip2> error code. + +Below is a list of the valid options: + +=over 5 + +=item B<$appendOutput> + +Controls whether the compressed data is appended to the output buffer in the +C<bzinflate>, C<bzflush> and C<bzclose> methods. + +Defaults to 1. + +=item B<$consumeInput> + +=item B<$small> + +To quote the bzip2 documentation + + If small is nonzero, the library will use an alternative decompression + algorithm which uses less memory but at the cost of decompressing more + slowly (roughly speaking, half the speed, but the maximum memory + requirement drops to around 2300k). + +Defaults to 0. + +=item B<$limitOutput> + +The C<LimitOutput> option changes the behavior of the C<< $i->bzinflate >> +method so that the amount of memory used by the output buffer can be +limited. + +When C<LimitOutput> is used the size of the output buffer used will either +be the 16k or the amount of memory already allocated to C<$output>, +whichever is larger. Predicting the output size available is tricky, so +don't rely on getting an exact output buffer size. + +When C<LimitOutout> is not specified C<< $i->bzinflate >> will use as much +memory as it takes to write all the uncompressed data it creates by +uncompressing the input buffer. + +If C<LimitOutput> is enabled, the C<ConsumeInput> option will also be +enabled. + +This option defaults to false. + +=back + +=head2 $status = $z->bzinflate($input, $output); + +Uncompresses C<$input> and writes the uncompressed data to C<$output>. + +Returns C<BZ_OK> if the uncompression was successful, but the end of the +compressed data stream has not been reached. Returns C<BZ_STREAM_END> on +successful uncompression and the end of the compression stream has been +reached. + +If C<consumeInput> is enabled in the constructor for the bunzip2 object, +C<$input> will have all compressed data removed from it after +uncompression. On C<BZ_OK> return this will mean that C<$input> will be an +empty string; when C<BZ_STREAM_END> C<$input> will either be an empty +string or will contain whatever data immediately followed the compressed +data stream. + +If C<appendOutput> is enabled in the constructor for the bunzip2 object, +the uncompressed data will be appended to C<$output>. If not enabled, +C<$output> will be truncated before the uncompressed data is written to it. + +=head1 Misc + +=head2 my $version = Compress::Raw::Bzip2::bzlibversion(); + +Returns the version of the underlying bzip2 library. + +=head1 Constants + +The following bzip2 constants are exported by this module + + BZ_RUN + BZ_FLUSH + BZ_FINISH + + BZ_OK + BZ_RUN_OK + BZ_FLUSH_OK + BZ_FINISH_OK + BZ_STREAM_END + BZ_SEQUENCE_ERROR + BZ_PARAM_ERROR + BZ_MEM_ERROR + BZ_DATA_ERROR + BZ_DATA_ERROR_MAGIC + BZ_IO_ERROR + BZ_UNEXPECTED_EOF + BZ_OUTBUFF_FULL + BZ_CONFIG_ERROR + +=head1 SEE ALSO + +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> + +L<Compress::Zlib::FAQ|Compress::Zlib::FAQ> + +L<File::GlobMapper|File::GlobMapper>, L<Archive::Zip|Archive::Zip>, +L<Archive::Tar|Archive::Tar>, +L<IO::Zlib|IO::Zlib> + +The primary site for the bzip2 program is F<http://www.bzip.org>. + +See the module L<Compress::Bzip2|Compress::Bzip2> + +=head1 AUTHOR + +This module was written by Paul Marquess, F<pmqs@cpan.org>. + +=head1 MODIFICATION HISTORY + +See the Changes file. + +=head1 COPYRIGHT AND LICENSE + +Copyright (c) 2005-2010 Paul Marquess. All rights reserved. + +This program is free software; you can redistribute it and/or +modify it under the same terms as Perl itself. + diff --git a/Master/tlpkg/tlperl/lib/Compress/Raw/Zlib.pm b/Master/tlpkg/tlperl/lib/Compress/Raw/Zlib.pm new file mode 100755 index 00000000000..79c96b76ccd --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Compress/Raw/Zlib.pm @@ -0,0 +1,1419 @@ + +package Compress::Raw::Zlib; + +require 5.004 ; +require Exporter; +use AutoLoader; +use Carp ; + +#use Parse::Parameters; + +use strict ; +use warnings ; +use bytes ; +our ($VERSION, $XS_VERSION, @ISA, @EXPORT, $AUTOLOAD); + +$VERSION = '2.024'; +$XS_VERSION = $VERSION; +$VERSION = eval $VERSION; + +@ISA = qw(Exporter); +# Items to export into callers namespace by default. Note: do not export +# names by default without a very good reason. Use EXPORT_OK instead. +# Do not simply export all your public functions/methods/constants. +@EXPORT = qw( + adler32 crc32 + + ZLIB_VERSION + ZLIB_VERNUM + + DEF_WBITS + OS_CODE + + MAX_MEM_LEVEL + MAX_WBITS + + Z_ASCII + Z_BEST_COMPRESSION + Z_BEST_SPEED + Z_BINARY + Z_BLOCK + Z_BUF_ERROR + Z_DATA_ERROR + Z_DEFAULT_COMPRESSION + Z_DEFAULT_STRATEGY + Z_DEFLATED + Z_ERRNO + Z_FILTERED + Z_FIXED + Z_FINISH + Z_FULL_FLUSH + Z_HUFFMAN_ONLY + Z_MEM_ERROR + Z_NEED_DICT + Z_NO_COMPRESSION + Z_NO_FLUSH + Z_NULL + Z_OK + Z_PARTIAL_FLUSH + Z_RLE + Z_STREAM_END + Z_STREAM_ERROR + Z_SYNC_FLUSH + Z_UNKNOWN + Z_VERSION_ERROR + + WANT_GZIP + WANT_GZIP_OR_ZLIB +); + +use constant WANT_GZIP => 16; +use constant WANT_GZIP_OR_ZLIB => 32; + +sub AUTOLOAD { + my($constname); + ($constname = $AUTOLOAD) =~ s/.*:://; + my ($error, $val) = constant($constname); + Carp::croak $error if $error; + no strict 'refs'; + *{$AUTOLOAD} = sub { $val }; + goto &{$AUTOLOAD}; +} + +use constant FLAG_APPEND => 1 ; +use constant FLAG_CRC => 2 ; +use constant FLAG_ADLER => 4 ; +use constant FLAG_CONSUME_INPUT => 8 ; +use constant FLAG_LIMIT_OUTPUT => 16 ; + +eval { + require XSLoader; + XSLoader::load('Compress::Raw::Zlib', $XS_VERSION); + 1; +} +or do { + require DynaLoader; + local @ISA = qw(DynaLoader); + bootstrap Compress::Raw::Zlib $XS_VERSION ; +}; + + +use constant Parse_any => 0x01; +use constant Parse_unsigned => 0x02; +use constant Parse_signed => 0x04; +use constant Parse_boolean => 0x08; +use constant Parse_string => 0x10; +use constant Parse_custom => 0x12; + +use constant Parse_store_ref => 0x100 ; + +use constant OFF_PARSED => 0 ; +use constant OFF_TYPE => 1 ; +use constant OFF_DEFAULT => 2 ; +use constant OFF_FIXED => 3 ; +use constant OFF_FIRST_ONLY => 4 ; +use constant OFF_STICKY => 5 ; + + + +sub ParseParameters +{ + my $level = shift || 0 ; + + my $sub = (caller($level + 1))[3] ; + #local $Carp::CarpLevel = 1 ; + my $p = new Compress::Raw::Zlib::Parameters() ; + $p->parse(@_) + or croak "$sub: $p->{Error}" ; + + return $p; +} + + +sub Compress::Raw::Zlib::Parameters::new +{ + my $class = shift ; + + my $obj = { Error => '', + Got => {}, + } ; + + #return bless $obj, ref($class) || $class || __PACKAGE__ ; + return bless $obj, 'Compress::Raw::Zlib::Parameters' ; +} + +sub Compress::Raw::Zlib::Parameters::setError +{ + my $self = shift ; + my $error = shift ; + my $retval = @_ ? shift : undef ; + + $self->{Error} = $error ; + return $retval; +} + +#sub getError +#{ +# my $self = shift ; +# return $self->{Error} ; +#} + +sub Compress::Raw::Zlib::Parameters::parse +{ + my $self = shift ; + + my $default = shift ; + + my $got = $self->{Got} ; + my $firstTime = keys %{ $got } == 0 ; + + my (@Bad) ; + my @entered = () ; + + # Allow the options to be passed as a hash reference or + # as the complete hash. + if (@_ == 0) { + @entered = () ; + } + elsif (@_ == 1) { + my $href = $_[0] ; + return $self->setError("Expected even number of parameters, got 1") + if ! defined $href or ! ref $href or ref $href ne "HASH" ; + + foreach my $key (keys %$href) { + push @entered, $key ; + push @entered, \$href->{$key} ; + } + } + else { + my $count = @_; + return $self->setError("Expected even number of parameters, got $count") + if $count % 2 != 0 ; + + for my $i (0.. $count / 2 - 1) { + push @entered, $_[2* $i] ; + push @entered, \$_[2* $i+1] ; + } + } + + + while (my ($key, $v) = each %$default) + { + croak "need 4 params [@$v]" + if @$v != 4 ; + + my ($first_only, $sticky, $type, $value) = @$v ; + my $x ; + $self->_checkType($key, \$value, $type, 0, \$x) + or return undef ; + + $key = lc $key; + + if ($firstTime || ! $sticky) { + $got->{$key} = [0, $type, $value, $x, $first_only, $sticky] ; + } + + $got->{$key}[OFF_PARSED] = 0 ; + } + + for my $i (0.. @entered / 2 - 1) { + my $key = $entered[2* $i] ; + my $value = $entered[2* $i+1] ; + + #print "Key [$key] Value [$value]" ; + #print defined $$value ? "[$$value]\n" : "[undef]\n"; + + $key =~ s/^-// ; + my $canonkey = lc $key; + + if ($got->{$canonkey} && ($firstTime || + ! $got->{$canonkey}[OFF_FIRST_ONLY] )) + { + my $type = $got->{$canonkey}[OFF_TYPE] ; + my $s ; + $self->_checkType($key, $value, $type, 1, \$s) + or return undef ; + #$value = $$value unless $type & Parse_store_ref ; + $value = $$value ; + $got->{$canonkey} = [1, $type, $value, $s] ; + } + else + { push (@Bad, $key) } + } + + if (@Bad) { + my ($bad) = join(", ", @Bad) ; + return $self->setError("unknown key value(s) @Bad") ; + } + + return 1; +} + +sub Compress::Raw::Zlib::Parameters::_checkType +{ + my $self = shift ; + + my $key = shift ; + my $value = shift ; + my $type = shift ; + my $validate = shift ; + my $output = shift; + + #local $Carp::CarpLevel = $level ; + #print "PARSE $type $key $value $validate $sub\n" ; + if ( $type & Parse_store_ref) + { + #$value = $$value + # if ref ${ $value } ; + + $$output = $value ; + return 1; + } + + $value = $$value ; + + if ($type & Parse_any) + { + $$output = $value ; + return 1; + } + elsif ($type & Parse_unsigned) + { + return $self->setError("Parameter '$key' must be an unsigned int, got 'undef'") + if $validate && ! defined $value ; + return $self->setError("Parameter '$key' must be an unsigned int, got '$value'") + if $validate && $value !~ /^\d+$/; + + $$output = defined $value ? $value : 0 ; + return 1; + } + elsif ($type & Parse_signed) + { + return $self->setError("Parameter '$key' must be a signed int, got 'undef'") + if $validate && ! defined $value ; + return $self->setError("Parameter '$key' must be a signed int, got '$value'") + if $validate && $value !~ /^-?\d+$/; + + $$output = defined $value ? $value : 0 ; + return 1 ; + } + elsif ($type & Parse_boolean) + { + return $self->setError("Parameter '$key' must be an int, got '$value'") + if $validate && defined $value && $value !~ /^\d*$/; + $$output = defined $value ? $value != 0 : 0 ; + return 1; + } + elsif ($type & Parse_string) + { + $$output = defined $value ? $value : "" ; + return 1; + } + + $$output = $value ; + return 1; +} + + + +sub Compress::Raw::Zlib::Parameters::parsed +{ + my $self = shift ; + my $name = shift ; + + return $self->{Got}{lc $name}[OFF_PARSED] ; +} + +sub Compress::Raw::Zlib::Parameters::value +{ + my $self = shift ; + my $name = shift ; + + if (@_) + { + $self->{Got}{lc $name}[OFF_PARSED] = 1; + $self->{Got}{lc $name}[OFF_DEFAULT] = $_[0] ; + $self->{Got}{lc $name}[OFF_FIXED] = $_[0] ; + } + + return $self->{Got}{lc $name}[OFF_FIXED] ; +} + +sub Compress::Raw::Zlib::Deflate::new +{ + my $pkg = shift ; + my ($got) = ParseParameters(0, + { + 'AppendOutput' => [1, 1, Parse_boolean, 0], + 'CRC32' => [1, 1, Parse_boolean, 0], + 'ADLER32' => [1, 1, Parse_boolean, 0], + 'Bufsize' => [1, 1, Parse_unsigned, 4096], + + 'Level' => [1, 1, Parse_signed, Z_DEFAULT_COMPRESSION()], + 'Method' => [1, 1, Parse_unsigned, Z_DEFLATED()], + 'WindowBits' => [1, 1, Parse_signed, MAX_WBITS()], + 'MemLevel' => [1, 1, Parse_unsigned, MAX_MEM_LEVEL()], + 'Strategy' => [1, 1, Parse_unsigned, Z_DEFAULT_STRATEGY()], + 'Dictionary' => [1, 1, Parse_any, ""], + }, @_) ; + + + croak "Compress::Raw::Zlib::Deflate::new: Bufsize must be >= 1, you specified " . + $got->value('Bufsize') + unless $got->value('Bufsize') >= 1; + + my $flags = 0 ; + $flags |= FLAG_APPEND if $got->value('AppendOutput') ; + $flags |= FLAG_CRC if $got->value('CRC32') ; + $flags |= FLAG_ADLER if $got->value('ADLER32') ; + + my $windowBits = $got->value('WindowBits'); + $windowBits += MAX_WBITS() + if ($windowBits & MAX_WBITS()) == 0 ; + + _deflateInit($flags, + $got->value('Level'), + $got->value('Method'), + $windowBits, + $got->value('MemLevel'), + $got->value('Strategy'), + $got->value('Bufsize'), + $got->value('Dictionary')) ; + +} + +sub Compress::Raw::Zlib::Inflate::new +{ + my $pkg = shift ; + my ($got) = ParseParameters(0, + { + 'AppendOutput' => [1, 1, Parse_boolean, 0], + 'LimitOutput' => [1, 1, Parse_boolean, 0], + 'CRC32' => [1, 1, Parse_boolean, 0], + 'ADLER32' => [1, 1, Parse_boolean, 0], + 'ConsumeInput' => [1, 1, Parse_boolean, 1], + 'Bufsize' => [1, 1, Parse_unsigned, 4096], + + 'WindowBits' => [1, 1, Parse_signed, MAX_WBITS()], + 'Dictionary' => [1, 1, Parse_any, ""], + }, @_) ; + + + croak "Compress::Raw::Zlib::Inflate::new: Bufsize must be >= 1, you specified " . + $got->value('Bufsize') + unless $got->value('Bufsize') >= 1; + + my $flags = 0 ; + $flags |= FLAG_APPEND if $got->value('AppendOutput') ; + $flags |= FLAG_CRC if $got->value('CRC32') ; + $flags |= FLAG_ADLER if $got->value('ADLER32') ; + $flags |= FLAG_CONSUME_INPUT if $got->value('ConsumeInput') ; + $flags |= FLAG_LIMIT_OUTPUT if $got->value('LimitOutput') ; + + + my $windowBits = $got->value('WindowBits'); + $windowBits += MAX_WBITS() + if ($windowBits & MAX_WBITS()) == 0 ; + + _inflateInit($flags, $windowBits, $got->value('Bufsize'), + $got->value('Dictionary')) ; +} + +sub Compress::Raw::Zlib::InflateScan::new +{ + my $pkg = shift ; + my ($got) = ParseParameters(0, + { + 'CRC32' => [1, 1, Parse_boolean, 0], + 'ADLER32' => [1, 1, Parse_boolean, 0], + 'Bufsize' => [1, 1, Parse_unsigned, 4096], + + 'WindowBits' => [1, 1, Parse_signed, -MAX_WBITS()], + 'Dictionary' => [1, 1, Parse_any, ""], + }, @_) ; + + + croak "Compress::Raw::Zlib::InflateScan::new: Bufsize must be >= 1, you specified " . + $got->value('Bufsize') + unless $got->value('Bufsize') >= 1; + + my $flags = 0 ; + #$flags |= FLAG_APPEND if $got->value('AppendOutput') ; + $flags |= FLAG_CRC if $got->value('CRC32') ; + $flags |= FLAG_ADLER if $got->value('ADLER32') ; + #$flags |= FLAG_CONSUME_INPUT if $got->value('ConsumeInput') ; + + _inflateScanInit($flags, $got->value('WindowBits'), $got->value('Bufsize'), + '') ; +} + +sub Compress::Raw::Zlib::inflateScanStream::createDeflateStream +{ + my $pkg = shift ; + my ($got) = ParseParameters(0, + { + 'AppendOutput' => [1, 1, Parse_boolean, 0], + 'CRC32' => [1, 1, Parse_boolean, 0], + 'ADLER32' => [1, 1, Parse_boolean, 0], + 'Bufsize' => [1, 1, Parse_unsigned, 4096], + + 'Level' => [1, 1, Parse_signed, Z_DEFAULT_COMPRESSION()], + 'Method' => [1, 1, Parse_unsigned, Z_DEFLATED()], + 'WindowBits' => [1, 1, Parse_signed, - MAX_WBITS()], + 'MemLevel' => [1, 1, Parse_unsigned, MAX_MEM_LEVEL()], + 'Strategy' => [1, 1, Parse_unsigned, Z_DEFAULT_STRATEGY()], + }, @_) ; + + croak "Compress::Raw::Zlib::InflateScan::createDeflateStream: Bufsize must be >= 1, you specified " . + $got->value('Bufsize') + unless $got->value('Bufsize') >= 1; + + my $flags = 0 ; + $flags |= FLAG_APPEND if $got->value('AppendOutput') ; + $flags |= FLAG_CRC if $got->value('CRC32') ; + $flags |= FLAG_ADLER if $got->value('ADLER32') ; + + $pkg->_createDeflateStream($flags, + $got->value('Level'), + $got->value('Method'), + $got->value('WindowBits'), + $got->value('MemLevel'), + $got->value('Strategy'), + $got->value('Bufsize'), + ) ; + +} + +sub Compress::Raw::Zlib::inflateScanStream::inflate +{ + my $self = shift ; + my $buffer = $_[1]; + my $eof = $_[2]; + + my $status = $self->scan(@_); + + if ($status == Z_OK() && $_[2]) { + my $byte = ' '; + + $status = $self->scan(\$byte, $_[1]) ; + } + + return $status ; +} + +sub Compress::Raw::Zlib::deflateStream::deflateParams +{ + my $self = shift ; + my ($got) = ParseParameters(0, { + 'Level' => [1, 1, Parse_signed, undef], + 'Strategy' => [1, 1, Parse_unsigned, undef], + 'Bufsize' => [1, 1, Parse_unsigned, undef], + }, + @_) ; + + croak "Compress::Raw::Zlib::deflateParams needs Level and/or Strategy" + unless $got->parsed('Level') + $got->parsed('Strategy') + + $got->parsed('Bufsize'); + + croak "Compress::Raw::Zlib::Inflate::deflateParams: Bufsize must be >= 1, you specified " . + $got->value('Bufsize') + if $got->parsed('Bufsize') && $got->value('Bufsize') <= 1; + + my $flags = 0; + $flags |= 1 if $got->parsed('Level') ; + $flags |= 2 if $got->parsed('Strategy') ; + $flags |= 4 if $got->parsed('Bufsize') ; + + $self->_deflateParams($flags, $got->value('Level'), + $got->value('Strategy'), $got->value('Bufsize')); + +} + + +# Autoload methods go after __END__, and are processed by the autosplit program. + +1; +__END__ + + +=head1 NAME + +Compress::Raw::Zlib - Low-Level Interface to zlib compression library + +=head1 SYNOPSIS + + use Compress::Raw::Zlib ; + + ($d, $status) = new Compress::Raw::Zlib::Deflate( [OPT] ) ; + $status = $d->deflate($input, $output) ; + $status = $d->flush($output [, $flush_type]) ; + $d->deflateReset() ; + $d->deflateParams(OPTS) ; + $d->deflateTune(OPTS) ; + $d->dict_adler() ; + $d->crc32() ; + $d->adler32() ; + $d->total_in() ; + $d->total_out() ; + $d->msg() ; + $d->get_Strategy(); + $d->get_Level(); + $d->get_BufSize(); + + ($i, $status) = new Compress::Raw::Zlib::Inflate( [OPT] ) ; + $status = $i->inflate($input, $output [, $eof]) ; + $status = $i->inflateSync($input) ; + $i->dict_adler() ; + $d->crc32() ; + $d->adler32() ; + $i->total_in() ; + $i->total_out() ; + $i->msg() ; + $d->get_BufSize(); + + $crc = adler32($buffer [,$crc]) ; + $crc = crc32($buffer [,$crc]) ; + + $crc = adler32_combine($crc1, $crc2, $len2)l + $crc = crc32_combine($adler1, $adler2, $len2) + + my $version = Compress::Raw::Zlib::zlib_version(); + +=head1 DESCRIPTION + +The I<Compress::Raw::Zlib> module provides a Perl interface to the I<zlib> +compression library (see L</AUTHOR> for details about where to get +I<zlib>). + +=head1 Compress::Raw::Zlib::Deflate + +This section defines an interface that allows in-memory compression using +the I<deflate> interface provided by zlib. + +Here is a definition of the interface available: + +=head2 B<($d, $status) = new Compress::Raw::Zlib::Deflate( [OPT] ) > + +Initialises a deflation object. + +If you are familiar with the I<zlib> library, it combines the +features of the I<zlib> functions C<deflateInit>, C<deflateInit2> +and C<deflateSetDictionary>. + +If successful, it will return the initialised deflation object, C<$d> +and a C<$status> of C<Z_OK> in a list context. In scalar context it +returns the deflation object, C<$d>, only. + +If not successful, the returned deflation object, C<$d>, will be +I<undef> and C<$status> will hold the a I<zlib> error code. + +The function optionally takes a number of named options specified as +C<< Name => value >> pairs. This allows individual options to be +tailored without having to specify them all in the parameter list. + +For backward compatibility, it is also possible to pass the parameters +as a reference to a hash containing the name=>value pairs. + +Below is a list of the valid options: + +=over 5 + +=item B<-Level> + +Defines the compression level. Valid values are 0 through 9, +C<Z_NO_COMPRESSION>, C<Z_BEST_SPEED>, C<Z_BEST_COMPRESSION>, and +C<Z_DEFAULT_COMPRESSION>. + +The default is C<Z_DEFAULT_COMPRESSION>. + +=item B<-Method> + +Defines the compression method. The only valid value at present (and +the default) is Z_DEFLATED. + +=item B<-WindowBits> + +To compress an RFC 1950 data stream, set C<WindowBits> to a positive +number between 8 and 15. + +To compress an RFC 1951 data stream, set C<WindowBits> to C<-MAX_WBITS>. + +To compress an RFC 1952 data stream (i.e. gzip), set C<WindowBits> to +C<WANT_GZIP>. + +For a definition of the meaning and valid values for C<WindowBits> +refer to the I<zlib> documentation for I<deflateInit2>. + +Defaults to C<MAX_WBITS>. + +=item B<-MemLevel> + +For a definition of the meaning and valid values for C<MemLevel> +refer to the I<zlib> documentation for I<deflateInit2>. + +Defaults to MAX_MEM_LEVEL. + +=item B<-Strategy> + +Defines the strategy used to tune the compression. The valid values are +C<Z_DEFAULT_STRATEGY>, C<Z_FILTERED>, C<Z_RLE>, C<Z_FIXED> and +C<Z_HUFFMAN_ONLY>. + +The default is Z_DEFAULT_STRATEGY. + +=item B<-Dictionary> + +When a dictionary is specified I<Compress::Raw::Zlib> will automatically +call C<deflateSetDictionary> directly after calling C<deflateInit>. The +Adler32 value for the dictionary can be obtained by calling the method +C<$d-E<gt>dict_adler()>. + +The default is no dictionary. + +=item B<-Bufsize> + +Sets the initial size for the output buffer used by the C<$d-E<gt>deflate> +and C<$d-E<gt>flush> methods. If the buffer has to be +reallocated to increase the size, it will grow in increments of +C<Bufsize>. + +The default buffer size is 4096. + +=item B<-AppendOutput> + +This option controls how data is written to the output buffer by the +C<$d-E<gt>deflate> and C<$d-E<gt>flush> methods. + +If the C<AppendOutput> option is set to false, the output buffers in the +C<$d-E<gt>deflate> and C<$d-E<gt>flush> methods will be truncated before +uncompressed data is written to them. + +If the option is set to true, uncompressed data will be appended to the +output buffer in the C<$d-E<gt>deflate> and C<$d-E<gt>flush> methods. + +This option defaults to false. + +=item B<-CRC32> + +If set to true, a crc32 checksum of the uncompressed data will be +calculated. Use the C<$d-E<gt>crc32> method to retrieve this value. + +This option defaults to false. + +=item B<-ADLER32> + +If set to true, an adler32 checksum of the uncompressed data will be +calculated. Use the C<$d-E<gt>adler32> method to retrieve this value. + +This option defaults to false. + +=back + +Here is an example of using the C<Compress::Raw::Zlib::Deflate> optional +parameter list to override the default buffer size and compression +level. All other options will take their default values. + + my $d = new Compress::Raw::Zlib::Deflate ( -Bufsize => 300, + -Level => Z_BEST_SPEED ) ; + +=head2 B<$status = $d-E<gt>deflate($input, $output)> + +Deflates the contents of C<$input> and writes the compressed data to +C<$output>. + +The C<$input> and C<$output> parameters can be either scalars or scalar +references. + +When finished, C<$input> will be completely processed (assuming there +were no errors). If the deflation was successful it writes the deflated +data to C<$output> and returns a status value of C<Z_OK>. + +On error, it returns a I<zlib> error code. + +If the C<AppendOutput> option is set to true in the constructor for +the C<$d> object, the compressed data will be appended to C<$output>. If +it is false, C<$output> will be truncated before any compressed data is +written to it. + +B<Note>: This method will not necessarily write compressed data to +C<$output> every time it is called. So do not assume that there has been +an error if the contents of C<$output> is empty on returning from +this method. As long as the return code from the method is C<Z_OK>, +the deflate has succeeded. + +=head2 B<$status = $d-E<gt>flush($output [, $flush_type]) > + +Typically used to finish the deflation. Any pending output will be +written to C<$output>. + +Returns C<Z_OK> if successful. + +Note that flushing can seriously degrade the compression ratio, so it +should only be used to terminate a decompression (using C<Z_FINISH>) or +when you want to create a I<full flush point> (using C<Z_FULL_FLUSH>). + +By default the C<flush_type> used is C<Z_FINISH>. Other valid values +for C<flush_type> are C<Z_NO_FLUSH>, C<Z_PARTIAL_FLUSH>, C<Z_SYNC_FLUSH> +and C<Z_FULL_FLUSH>. It is strongly recommended that you only set the +C<flush_type> parameter if you fully understand the implications of +what it does. See the C<zlib> documentation for details. + +If the C<AppendOutput> option is set to true in the constructor for +the C<$d> object, the compressed data will be appended to C<$output>. If +it is false, C<$output> will be truncated before any compressed data is +written to it. + +=head2 B<$status = $d-E<gt>deflateReset() > + +This method will reset the deflation object C<$d>. It can be used when you +are compressing multiple data streams and want to use the same object to +compress each of them. It should only be used once the previous data stream +has been flushed successfully, i.e. a call to C<< $d->flush(Z_FINISH) >> has +returned C<Z_OK>. + +Returns C<Z_OK> if successful. + +=head2 B<$status = $d-E<gt>deflateParams([OPT])> + +Change settings for the deflate object C<$d>. + +The list of the valid options is shown below. Options not specified +will remain unchanged. + +=over 5 + +=item B<-Level> + +Defines the compression level. Valid values are 0 through 9, +C<Z_NO_COMPRESSION>, C<Z_BEST_SPEED>, C<Z_BEST_COMPRESSION>, and +C<Z_DEFAULT_COMPRESSION>. + +=item B<-Strategy> + +Defines the strategy used to tune the compression. The valid values are +C<Z_DEFAULT_STRATEGY>, C<Z_FILTERED> and C<Z_HUFFMAN_ONLY>. + +=item B<-BufSize> + +Sets the initial size for the output buffer used by the C<$d-E<gt>deflate> +and C<$d-E<gt>flush> methods. If the buffer has to be +reallocated to increase the size, it will grow in increments of +C<Bufsize>. + +=back + +=head2 B<$status = $d-E<gt>deflateTune($good_length, $max_lazy, $nice_length, $max_chain)> + +Tune the internal settings for the deflate object C<$d>. This option is +only available if you are running zlib 1.2.2.3 or better. + +Refer to the documentation in zlib.h for instructions on how to fly +C<deflateTune>. + +=head2 B<$d-E<gt>dict_adler()> + +Returns the adler32 value for the dictionary. + +=head2 B<$d-E<gt>crc32()> + +Returns the crc32 value for the uncompressed data to date. + +If the C<CRC32> option is not enabled in the constructor for this object, +this method will always return 0; + +=head2 B<$d-E<gt>adler32()> + +Returns the adler32 value for the uncompressed data to date. + +=head2 B<$d-E<gt>msg()> + +Returns the last error message generated by zlib. + +=head2 B<$d-E<gt>total_in()> + +Returns the total number of bytes uncompressed bytes input to deflate. + +=head2 B<$d-E<gt>total_out()> + +Returns the total number of compressed bytes output from deflate. + +=head2 B<$d-E<gt>get_Strategy()> + +Returns the deflation strategy currently used. Valid values are +C<Z_DEFAULT_STRATEGY>, C<Z_FILTERED> and C<Z_HUFFMAN_ONLY>. + +=head2 B<$d-E<gt>get_Level()> + +Returns the compression level being used. + +=head2 B<$d-E<gt>get_BufSize()> + +Returns the buffer size used to carry out the compression. + +=head2 Example + +Here is a trivial example of using C<deflate>. It simply reads standard +input, deflates it and writes it to standard output. + + use strict ; + use warnings ; + + use Compress::Raw::Zlib ; + + binmode STDIN; + binmode STDOUT; + my $x = new Compress::Raw::Zlib::Deflate + or die "Cannot create a deflation stream\n" ; + + my ($output, $status) ; + while (<>) + { + $status = $x->deflate($_, $output) ; + + $status == Z_OK + or die "deflation failed\n" ; + + print $output ; + } + + $status = $x->flush($output) ; + + $status == Z_OK + or die "deflation failed\n" ; + + print $output ; + +=head1 Compress::Raw::Zlib::Inflate + +This section defines an interface that allows in-memory uncompression using +the I<inflate> interface provided by zlib. + +Here is a definition of the interface: + +=head2 B< ($i, $status) = new Compress::Raw::Zlib::Inflate( [OPT] ) > + +Initialises an inflation object. + +In a list context it returns the inflation object, C<$i>, and the +I<zlib> status code (C<$status>). In a scalar context it returns the +inflation object only. + +If successful, C<$i> will hold the inflation object and C<$status> will +be C<Z_OK>. + +If not successful, C<$i> will be I<undef> and C<$status> will hold the +I<zlib> error code. + +The function optionally takes a number of named options specified as +C<< -Name => value >> pairs. This allows individual options to be +tailored without having to specify them all in the parameter list. + +For backward compatibility, it is also possible to pass the parameters +as a reference to a hash containing the C<< name=>value >> pairs. + +Here is a list of the valid options: + +=over 5 + +=item B<-WindowBits> + +To uncompress an RFC 1950 data stream, set C<WindowBits> to a positive +number between 8 and 15. + +To uncompress an RFC 1951 data stream, set C<WindowBits> to C<-MAX_WBITS>. + +To uncompress an RFC 1952 data stream (i.e. gzip), set C<WindowBits> to +C<WANT_GZIP>. + +To auto-detect and uncompress an RFC 1950 or RFC 1952 data stream (i.e. +gzip), set C<WindowBits> to C<WANT_GZIP_OR_ZLIB>. + +For a full definition of the meaning and valid values for C<WindowBits> +refer to the I<zlib> documentation for I<inflateInit2>. + +Defaults to C<MAX_WBITS>. + +=item B<-Bufsize> + +Sets the initial size for the output buffer used by the C<$i-E<gt>inflate> +method. If the output buffer in this method has to be reallocated to +increase the size, it will grow in increments of C<Bufsize>. + +Default is 4096. + +=item B<-Dictionary> + +The default is no dictionary. + +=item B<-AppendOutput> + +This option controls how data is written to the output buffer by the +C<$i-E<gt>inflate> method. + +If the option is set to false, the output buffer in the C<$i-E<gt>inflate> +method will be truncated before uncompressed data is written to it. + +If the option is set to true, uncompressed data will be appended to the +output buffer by the C<$i-E<gt>inflate> method. + +This option defaults to false. + +=item B<-CRC32> + +If set to true, a crc32 checksum of the uncompressed data will be +calculated. Use the C<$i-E<gt>crc32> method to retrieve this value. + +This option defaults to false. + +=item B<-ADLER32> + +If set to true, an adler32 checksum of the uncompressed data will be +calculated. Use the C<$i-E<gt>adler32> method to retrieve this value. + +This option defaults to false. + +=item B<-ConsumeInput> + +If set to true, this option will remove compressed data from the input +buffer of the C<< $i->inflate >> method as the inflate progresses. + +This option can be useful when you are processing compressed data that is +embedded in another file/buffer. In this case the data that immediately +follows the compressed stream will be left in the input buffer. + +This option defaults to true. + +=item B<-LimitOutput> + +The C<LimitOutput> option changes the behavior of the C<< $i->inflate >> +method so that the amount of memory used by the output buffer can be +limited. + +When C<LimitOutput> is used the size of the output buffer used will either +be the value of the C<Bufsize> option or the amount of memory already +allocated to C<$output>, whichever is larger. Predicting the output size +available is tricky, so don't rely on getting an exact output buffer size. + +When C<LimitOutout> is not specified C<< $i->inflate >> will use as much +memory as it takes to write all the uncompressed data it creates by +uncompressing the input buffer. + +If C<LimitOutput> is enabled, the C<ConsumeInput> option will also be +enabled. + +This option defaults to false. + +See L</The LimitOutput option> for a discussion on why C<LimitOutput> is +needed and how to use it. + +=back + +Here is an example of using an optional parameter to override the default +buffer size. + + my ($i, $status) = new Compress::Raw::Zlib::Inflate( -Bufsize => 300 ) ; + +=head2 B< $status = $i-E<gt>inflate($input, $output [,$eof]) > + +Inflates the complete contents of C<$input> and writes the uncompressed +data to C<$output>. The C<$input> and C<$output> parameters can either be +scalars or scalar references. + +Returns C<Z_OK> if successful and C<Z_STREAM_END> if the end of the +compressed data has been successfully reached. + +If not successful C<$status> will hold the I<zlib> error code. + +If the C<ConsumeInput> option has been set to true when the +C<Compress::Raw::Zlib::Inflate> object is created, the C<$input> parameter +is modified by C<inflate>. On completion it will contain what remains +of the input buffer after inflation. In practice, this means that when +the return status is C<Z_OK> the C<$input> parameter will contain an +empty string, and when the return status is C<Z_STREAM_END> the C<$input> +parameter will contains what (if anything) was stored in the input buffer +after the deflated data stream. + +This feature is useful when processing a file format that encapsulates +a compressed data stream (e.g. gzip, zip) and there is useful data +immediately after the deflation stream. + +If the C<AppendOutput> option is set to true in the constructor for +this object, the uncompressed data will be appended to C<$output>. If +it is false, C<$output> will be truncated before any uncompressed data +is written to it. + +The C<$eof> parameter needs a bit of explanation. + +Prior to version 1.2.0, zlib assumed that there was at least one trailing +byte immediately after the compressed data stream when it was carrying out +decompression. This normally isn't a problem because the majority of zlib +applications guarantee that there will be data directly after the +compressed data stream. For example, both gzip (RFC 1950) and zip both +define trailing data that follows the compressed data stream. + +The C<$eof> parameter only needs to be used if B<all> of the following +conditions apply + +=over 5 + +=item 1 + +You are either using a copy of zlib that is older than version 1.2.0 or you +want your application code to be able to run with as many different +versions of zlib as possible. + +=item 2 + +You have set the C<WindowBits> parameter to C<-MAX_WBITS> in the constructor +for this object, i.e. you are uncompressing a raw deflated data stream +(RFC 1951). + +=item 3 + +There is no data immediately after the compressed data stream. + +=back + +If B<all> of these are the case, then you need to set the C<$eof> parameter +to true on the final call (and only the final call) to C<$i-E<gt>inflate>. + +If you have built this module with zlib >= 1.2.0, the C<$eof> parameter is +ignored. You can still set it if you want, but it won't be used behind the +scenes. + +=head2 B<$status = $i-E<gt>inflateSync($input)> + +This method can be used to attempt to recover good data from a compressed +data stream that is partially corrupt. +It scans C<$input> until it reaches either a I<full flush point> or the +end of the buffer. + +If a I<full flush point> is found, C<Z_OK> is returned and C<$input> +will be have all data up to the flush point removed. This data can then be +passed to the C<$i-E<gt>inflate> method to be uncompressed. + +Any other return code means that a flush point was not found. If more +data is available, C<inflateSync> can be called repeatedly with more +compressed data until the flush point is found. + +Note I<full flush points> are not present by default in compressed +data streams. They must have been added explicitly when the data stream +was created by calling C<Compress::Deflate::flush> with C<Z_FULL_FLUSH>. + +=head2 B<$i-E<gt>dict_adler()> + +Returns the adler32 value for the dictionary. + +=head2 B<$i-E<gt>crc32()> + +Returns the crc32 value for the uncompressed data to date. + +If the C<CRC32> option is not enabled in the constructor for this object, +this method will always return 0; + +=head2 B<$i-E<gt>adler32()> + +Returns the adler32 value for the uncompressed data to date. + +If the C<ADLER32> option is not enabled in the constructor for this object, +this method will always return 0; + +=head2 B<$i-E<gt>msg()> + +Returns the last error message generated by zlib. + +=head2 B<$i-E<gt>total_in()> + +Returns the total number of bytes compressed bytes input to inflate. + +=head2 B<$i-E<gt>total_out()> + +Returns the total number of uncompressed bytes output from inflate. + +=head2 B<$d-E<gt>get_BufSize()> + +Returns the buffer size used to carry out the decompression. + +=head2 Examples + +Here is an example of using C<inflate>. + + use strict ; + use warnings ; + + use Compress::Raw::Zlib; + + my $x = new Compress::Raw::Zlib::Inflate() + or die "Cannot create a inflation stream\n" ; + + my $input = '' ; + binmode STDIN; + binmode STDOUT; + + my ($output, $status) ; + while (read(STDIN, $input, 4096)) + { + $status = $x->inflate($input, $output) ; + + print $output ; + + last if $status != Z_OK ; + } + + die "inflation failed\n" + unless $status == Z_STREAM_END ; + +The next example show how to use the C<LimitOutput> option. Notice the use +of two nested loops in this case. The outer loop reads the data from the +input source - STDIN and the inner loop repeatedly calls C<inflate> until +C<$input> is exhausted, we get an error, or the end of the stream is +reached. One point worth remembering is by using the C<LimitOutput> option +you also get C<ConsumeInput> set as well - this makes the code below much +simpler. + + use strict ; + use warnings ; + + use Compress::Raw::Zlib; + + my $x = new Compress::Raw::Zlib::Inflate(LimitOutput => 1) + or die "Cannot create a inflation stream\n" ; + + my $input = '' ; + binmode STDIN; + binmode STDOUT; + + my ($output, $status) ; + + OUTER: + while (read(STDIN, $input, 4096)) + { + do + { + $status = $x->inflate($input, $output) ; + + print $output ; + + last OUTER + unless $status == Z_OK || $status == Z_BUF_ERROR ; + } + while ($status == Z_OK && length $input); + } + + die "inflation failed\n" + unless $status == Z_STREAM_END ; + +=head1 CHECKSUM FUNCTIONS + +Two functions are provided by I<zlib> to calculate checksums. For the +Perl interface, the order of the two parameters in both functions has +been reversed. This allows both running checksums and one off +calculations to be done. + + $crc = adler32($buffer [,$crc]) ; + $crc = crc32($buffer [,$crc]) ; + +The buffer parameters can either be a scalar or a scalar reference. + +If the $crc parameters is C<undef>, the crc value will be reset. + +If you have built this module with zlib 1.2.3 or better, two more +CRC-related functions are available. + + $crc = adler32_combine($crc1, $crc2, $len2)l + $crc = crc32_combine($adler1, $adler2, $len2) + +These functions allow checksums to be merged. + +=head1 Misc + +=head2 my $version = Compress::Raw::Zlib::zlib_version(); + +Returns the version of the zlib library. + +=head1 The LimitOutput option. + +By default C<< $i->inflate($input, $output) >> will uncompress I<all> data +in C<$input> and write I<all> of the uncompressed data it has generated to +C<$output>. This makes the interface to C<inflate> much simpler - if the +method has uncompressed C<$input> successfully I<all> compressed data in +C<$input> will have been dealt with. So if you are reading from an input +source and uncompressing as you go the code will look something like this + + use strict ; + use warnings ; + + use Compress::Raw::Zlib; + + my $x = new Compress::Raw::Zlib::Inflate() + or die "Cannot create a inflation stream\n" ; + + my $input = '' ; + + my ($output, $status) ; + while (read(STDIN, $input, 4096)) + { + $status = $x->inflate($input, $output) ; + + print $output ; + + last if $status != Z_OK ; + } + + die "inflation failed\n" + unless $status == Z_STREAM_END ; + +The points to note are + +=over 5 + +=item * + +The main processing loop in the code handles reading of compressed data +from STDIN. + +=item * + +The status code returned from C<inflate> will only trigger termination of +the main processing loop if it isn't C<Z_OK>. When C<LimitOutput> has not +been used the C<Z_OK> status means means that the end of the compressed +data stream has been reached or there has been an error in uncompression. + +=item * + +After the call to C<inflate> I<all> of the uncompressed data in C<$input> +will have been processed. This means the subsequent call to C<read> can +overwrite it's contents without any problem. + +=back + +For most use-cases the behavior described above is acceptable (this module +and it's predecessor, C<Compress::Zlib>, have used it for over 10 years +without an issue), but in a few very specific use-cases the amount of +memory required for C<$output> can prohibitively large. For example, if the +compressed data stream contains the same pattern repeated thousands of +times, a relatively small compressed data stream can uncompress into +hundreds of megabytes. Remember C<inflate> will keep allocating memory +until I<all> the uncompressed data has been written to the output buffer - +the size of C<$output> is unbounded. + +The C<LimitOutput> option is designed to help with this use-case. + +The main difference in your code when using C<LimitOutput> is having to +deal with cases where the C<$input> parameter still contains some +uncompressed data that C<inflate> hasn't processed yet. The status code +returned from C<inflate> will be C<Z_OK> if uncompression took place and +C<Z_BUF_ERROR> if the output buffer is full. + +Below is typical code that shows how to use C<LimitOutput>. + + use strict ; + use warnings ; + + use Compress::Raw::Zlib; + + my $x = new Compress::Raw::Zlib::Inflate(LimitOutput => 1) + or die "Cannot create a inflation stream\n" ; + + my $input = '' ; + binmode STDIN; + binmode STDOUT; + + my ($output, $status) ; + + OUTER: + while (read(STDIN, $input, 4096)) + { + do + { + $status = $x->inflate($input, $output) ; + + print $output ; + + last OUTER + unless $status == Z_OK || $status == Z_BUF_ERROR ; + } + while ($status == Z_OK && length $input); + } + + die "inflation failed\n" + unless $status == Z_STREAM_END ; + +Points to note this time: + +=over 5 + +=item * + +There are now two nested loops in the code: the outer loop for reading the +compressed data from STDIN, as before; and the inner loop to carry out the +uncompression. + +=item * + +There are two exit points from the inner uncompression loop. + +Firstly when C<inflate> has returned a status other than C<Z_OK> or +C<Z_BUF_ERROR>. This means that either the end of the compressed data +stream has been reached (C<Z_STREAM_END>) or there is an error in the +compressed data. In either of these cases there is no point in continuing +with reading the compressed data, so both loops are terminated. + +The second exit point tests if there is any data left in the input buffer, +C<$input> - remember that the C<ConsumeInput> option is automatically +enabled when C<LimitOutput> is used. When the input buffer has been +exhausted, the outer loop can run again and overwrite a now empty +C<$input>. + +=back + +=head1 ACCESSING ZIP FILES + +Although it is possible (with some effort on your part) to use this module +to access .zip files, there are other perl modules available that will +do all the hard work for you. Check out C<Archive::Zip>, +C<IO::Compress::Zip> and C<IO::Uncompress::Unzip>. + +=head1 CONSTANTS + +All the I<zlib> constants are automatically imported when you make use +of I<Compress::Raw::Zlib>. + +=head1 SEE ALSO + +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> + +L<Compress::Zlib::FAQ|Compress::Zlib::FAQ> + +L<File::GlobMapper|File::GlobMapper>, L<Archive::Zip|Archive::Zip>, +L<Archive::Tar|Archive::Tar>, +L<IO::Zlib|IO::Zlib> + +For RFC 1950, 1951 and 1952 see +F<http://www.faqs.org/rfcs/rfc1950.html>, +F<http://www.faqs.org/rfcs/rfc1951.html> and +F<http://www.faqs.org/rfcs/rfc1952.html> + +The I<zlib> compression library was written by Jean-loup Gailly +F<gzip@prep.ai.mit.edu> and Mark Adler F<madler@alumni.caltech.edu>. + +The primary site for the I<zlib> compression library is +F<http://www.zlib.org>. + +The primary site for gzip is F<http://www.gzip.org>. + +=head1 AUTHOR + +This module was written by Paul Marquess, F<pmqs@cpan.org>. + +=head1 MODIFICATION HISTORY + +See the Changes file. + +=head1 COPYRIGHT AND LICENSE + +Copyright (c) 2005-2010 Paul Marquess. All rights reserved. + +This program is free software; you can redistribute it and/or +modify it under the same terms as Perl itself. + diff --git a/Master/tlpkg/tlperl/lib/Compress/Zlib.pm b/Master/tlpkg/tlperl/lib/Compress/Zlib.pm new file mode 100755 index 00000000000..9424df63b8b --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Compress/Zlib.pm @@ -0,0 +1,1494 @@ + +package Compress::Zlib; + +require 5.004 ; +require Exporter; +use AutoLoader; +use Carp ; +use IO::Handle ; +use Scalar::Util qw(dualvar); + +use IO::Compress::Base::Common 2.024 ; +use Compress::Raw::Zlib 2.024 ; +use IO::Compress::Gzip 2.024 ; +use IO::Uncompress::Gunzip 2.024 ; + +use strict ; +use warnings ; +use bytes ; +our ($VERSION, $XS_VERSION, @ISA, @EXPORT, @EXPORT_OK, %EXPORT_TAGS, $AUTOLOAD); + +$VERSION = '2.024'; +$XS_VERSION = $VERSION; +$VERSION = eval $VERSION; + +@ISA = qw(Exporter); +# Items to export into callers namespace by default. Note: do not export +# names by default without a very good reason. Use EXPORT_OK instead. +# Do not simply export all your public functions/methods/constants. +@EXPORT = qw( + deflateInit inflateInit + + compress uncompress + + gzopen $gzerrno + ); + +push @EXPORT, @Compress::Raw::Zlib::EXPORT ; + +@EXPORT_OK = qw(memGunzip memGzip zlib_version); +%EXPORT_TAGS = ( + ALL => \@EXPORT +); + +BEGIN +{ + *zlib_version = \&Compress::Raw::Zlib::zlib_version; +} + +sub AUTOLOAD { + my($constname); + ($constname = $AUTOLOAD) =~ s/.*:://; + my ($error, $val) = Compress::Raw::Zlib::constant($constname); + Carp::croak $error if $error; + no strict 'refs'; + *{$AUTOLOAD} = sub { $val }; + goto &{$AUTOLOAD}; +} + +use constant FLAG_APPEND => 1 ; +use constant FLAG_CRC => 2 ; +use constant FLAG_ADLER => 4 ; +use constant FLAG_CONSUME_INPUT => 8 ; + +our (@my_z_errmsg); + +@my_z_errmsg = ( + "need dictionary", # Z_NEED_DICT 2 + "stream end", # Z_STREAM_END 1 + "", # Z_OK 0 + "file error", # Z_ERRNO (-1) + "stream error", # Z_STREAM_ERROR (-2) + "data error", # Z_DATA_ERROR (-3) + "insufficient memory", # Z_MEM_ERROR (-4) + "buffer error", # Z_BUF_ERROR (-5) + "incompatible version",# Z_VERSION_ERROR(-6) + ); + + +sub _set_gzerr +{ + my $value = shift ; + + if ($value == 0) { + $Compress::Zlib::gzerrno = 0 ; + } + elsif ($value == Z_ERRNO() || $value > 2) { + $Compress::Zlib::gzerrno = $! ; + } + else { + $Compress::Zlib::gzerrno = dualvar($value+0, $my_z_errmsg[2 - $value]); + } + + return $value ; +} + +sub _set_gzerr_undef +{ + _set_gzerr(@_); + return undef; +} +sub _save_gzerr +{ + my $gz = shift ; + my $test_eof = shift ; + + my $value = $gz->errorNo() || 0 ; + + if ($test_eof) { + #my $gz = $self->[0] ; + # gzread uses Z_STREAM_END to denote a successful end + $value = Z_STREAM_END() if $gz->eof() && $value == 0 ; + } + + _set_gzerr($value) ; +} + +sub gzopen($$) +{ + my ($file, $mode) = @_ ; + + my $gz ; + my %defOpts = (Level => Z_DEFAULT_COMPRESSION(), + Strategy => Z_DEFAULT_STRATEGY(), + ); + + my $writing ; + $writing = ! ($mode =~ /r/i) ; + $writing = ($mode =~ /[wa]/i) ; + + $defOpts{Level} = $1 if $mode =~ /(\d)/; + $defOpts{Strategy} = Z_FILTERED() if $mode =~ /f/i; + $defOpts{Strategy} = Z_HUFFMAN_ONLY() if $mode =~ /h/i; + $defOpts{Append} = 1 if $mode =~ /a/i; + + my $infDef = $writing ? 'deflate' : 'inflate'; + my @params = () ; + + croak "gzopen: file parameter is not a filehandle or filename" + unless isaFilehandle $file || isaFilename $file || + (ref $file && ref $file eq 'SCALAR'); + + return undef unless $mode =~ /[rwa]/i ; + + _set_gzerr(0) ; + + if ($writing) { + $gz = new IO::Compress::Gzip($file, Minimal => 1, AutoClose => 1, + %defOpts) + or $Compress::Zlib::gzerrno = $IO::Compress::Gzip::GzipError; + } + else { + $gz = new IO::Uncompress::Gunzip($file, + Transparent => 1, + Append => 0, + AutoClose => 1, + MultiStream => 1, + Strict => 0) + or $Compress::Zlib::gzerrno = $IO::Uncompress::Gunzip::GunzipError; + } + + return undef + if ! defined $gz ; + + bless [$gz, $infDef], 'Compress::Zlib::gzFile'; +} + +sub Compress::Zlib::gzFile::gzread +{ + my $self = shift ; + + return _set_gzerr(Z_STREAM_ERROR()) + if $self->[1] ne 'inflate'; + + my $len = defined $_[1] ? $_[1] : 4096 ; + + if ($self->gzeof() || $len == 0) { + # Zap the output buffer to match ver 1 behaviour. + $_[0] = "" ; + return 0 ; + } + + my $gz = $self->[0] ; + my $status = $gz->read($_[0], $len) ; + _save_gzerr($gz, 1); + return $status ; +} + +sub Compress::Zlib::gzFile::gzreadline +{ + my $self = shift ; + + my $gz = $self->[0] ; + { + # Maintain backward compatibility with 1.x behaviour + # It didn't support $/, so this can't either. + local $/ = "\n" ; + $_[0] = $gz->getline() ; + } + _save_gzerr($gz, 1); + return defined $_[0] ? length $_[0] : 0 ; +} + +sub Compress::Zlib::gzFile::gzwrite +{ + my $self = shift ; + my $gz = $self->[0] ; + + return _set_gzerr(Z_STREAM_ERROR()) + if $self->[1] ne 'deflate'; + + $] >= 5.008 and (utf8::downgrade($_[0], 1) + or croak "Wide character in gzwrite"); + + my $status = $gz->write($_[0]) ; + _save_gzerr($gz); + return $status ; +} + +sub Compress::Zlib::gzFile::gztell +{ + my $self = shift ; + my $gz = $self->[0] ; + my $status = $gz->tell() ; + _save_gzerr($gz); + return $status ; +} + +sub Compress::Zlib::gzFile::gzseek +{ + my $self = shift ; + my $offset = shift ; + my $whence = shift ; + + my $gz = $self->[0] ; + my $status ; + eval { $status = $gz->seek($offset, $whence) ; }; + if ($@) + { + my $error = $@; + $error =~ s/^.*: /gzseek: /; + $error =~ s/ at .* line \d+\s*$//; + croak $error; + } + _save_gzerr($gz); + return $status ; +} + +sub Compress::Zlib::gzFile::gzflush +{ + my $self = shift ; + my $f = shift ; + + my $gz = $self->[0] ; + my $status = $gz->flush($f) ; + my $err = _save_gzerr($gz); + return $status ? 0 : $err; +} + +sub Compress::Zlib::gzFile::gzclose +{ + my $self = shift ; + my $gz = $self->[0] ; + + my $status = $gz->close() ; + my $err = _save_gzerr($gz); + return $status ? 0 : $err; +} + +sub Compress::Zlib::gzFile::gzeof +{ + my $self = shift ; + my $gz = $self->[0] ; + + return 0 + if $self->[1] ne 'inflate'; + + my $status = $gz->eof() ; + _save_gzerr($gz); + return $status ; +} + +sub Compress::Zlib::gzFile::gzsetparams +{ + my $self = shift ; + croak "Usage: Compress::Zlib::gzFile::gzsetparams(file, level, strategy)" + unless @_ eq 2 ; + + my $gz = $self->[0] ; + my $level = shift ; + my $strategy = shift; + + return _set_gzerr(Z_STREAM_ERROR()) + if $self->[1] ne 'deflate'; + + my $status = *$gz->{Compress}->deflateParams(-Level => $level, + -Strategy => $strategy); + _save_gzerr($gz); + return $status ; +} + +sub Compress::Zlib::gzFile::gzerror +{ + my $self = shift ; + my $gz = $self->[0] ; + + return $Compress::Zlib::gzerrno ; +} + + +sub compress($;$) +{ + my ($x, $output, $err, $in) =('', '', '', '') ; + + if (ref $_[0] ) { + $in = $_[0] ; + croak "not a scalar reference" unless ref $in eq 'SCALAR' ; + } + else { + $in = \$_[0] ; + } + + $] >= 5.008 and (utf8::downgrade($$in, 1) + or croak "Wide character in compress"); + + my $level = (@_ == 2 ? $_[1] : Z_DEFAULT_COMPRESSION() ); + + $x = new Compress::Raw::Zlib::Deflate -AppendOutput => 1, -Level => $level + or return undef ; + + $err = $x->deflate($in, $output) ; + return undef unless $err == Z_OK() ; + + $err = $x->flush($output) ; + return undef unless $err == Z_OK() ; + + return $output ; + +} + +sub uncompress($) +{ + my ($x, $output, $err, $in) =('', '', '', '') ; + + if (ref $_[0] ) { + $in = $_[0] ; + croak "not a scalar reference" unless ref $in eq 'SCALAR' ; + } + else { + $in = \$_[0] ; + } + + $] >= 5.008 and (utf8::downgrade($$in, 1) + or croak "Wide character in uncompress"); + + $x = new Compress::Raw::Zlib::Inflate -ConsumeInput => 0 or return undef ; + + $err = $x->inflate($in, $output) ; + return undef unless $err == Z_STREAM_END() ; + + return $output ; +} + + + +sub deflateInit(@) +{ + my ($got) = ParseParameters(0, + { + 'Bufsize' => [1, 1, Parse_unsigned, 4096], + 'Level' => [1, 1, Parse_signed, Z_DEFAULT_COMPRESSION()], + 'Method' => [1, 1, Parse_unsigned, Z_DEFLATED()], + 'WindowBits' => [1, 1, Parse_signed, MAX_WBITS()], + 'MemLevel' => [1, 1, Parse_unsigned, MAX_MEM_LEVEL()], + 'Strategy' => [1, 1, Parse_unsigned, Z_DEFAULT_STRATEGY()], + 'Dictionary' => [1, 1, Parse_any, ""], + }, @_ ) ; + + croak "Compress::Zlib::deflateInit: Bufsize must be >= 1, you specified " . + $got->value('Bufsize') + unless $got->value('Bufsize') >= 1; + + my $obj ; + + my $status = 0 ; + ($obj, $status) = + Compress::Raw::Zlib::_deflateInit(0, + $got->value('Level'), + $got->value('Method'), + $got->value('WindowBits'), + $got->value('MemLevel'), + $got->value('Strategy'), + $got->value('Bufsize'), + $got->value('Dictionary')) ; + + my $x = ($status == Z_OK() ? bless $obj, "Zlib::OldDeflate" : undef) ; + return wantarray ? ($x, $status) : $x ; +} + +sub inflateInit(@) +{ + my ($got) = ParseParameters(0, + { + 'Bufsize' => [1, 1, Parse_unsigned, 4096], + 'WindowBits' => [1, 1, Parse_signed, MAX_WBITS()], + 'Dictionary' => [1, 1, Parse_any, ""], + }, @_) ; + + + croak "Compress::Zlib::inflateInit: Bufsize must be >= 1, you specified " . + $got->value('Bufsize') + unless $got->value('Bufsize') >= 1; + + my $status = 0 ; + my $obj ; + ($obj, $status) = Compress::Raw::Zlib::_inflateInit(FLAG_CONSUME_INPUT, + $got->value('WindowBits'), + $got->value('Bufsize'), + $got->value('Dictionary')) ; + + my $x = ($status == Z_OK() ? bless $obj, "Zlib::OldInflate" : undef) ; + + wantarray ? ($x, $status) : $x ; +} + +package Zlib::OldDeflate ; + +our (@ISA); +@ISA = qw(Compress::Raw::Zlib::deflateStream); + + +sub deflate +{ + my $self = shift ; + my $output ; + + my $status = $self->SUPER::deflate($_[0], $output) ; + wantarray ? ($output, $status) : $output ; +} + +sub flush +{ + my $self = shift ; + my $output ; + my $flag = shift || Compress::Zlib::Z_FINISH(); + my $status = $self->SUPER::flush($output, $flag) ; + + wantarray ? ($output, $status) : $output ; +} + +package Zlib::OldInflate ; + +our (@ISA); +@ISA = qw(Compress::Raw::Zlib::inflateStream); + +sub inflate +{ + my $self = shift ; + my $output ; + my $status = $self->SUPER::inflate($_[0], $output) ; + wantarray ? ($output, $status) : $output ; +} + +package Compress::Zlib ; + +use IO::Compress::Gzip::Constants 2.024 ; + +sub memGzip($) +{ + my $out; + + # if the deflation buffer isn't a reference, make it one + my $string = (ref $_[0] ? $_[0] : \$_[0]) ; + + $] >= 5.008 and (utf8::downgrade($$string, 1) + or croak "Wide character in memGzip"); + + _set_gzerr(0); + if ( ! IO::Compress::Gzip::gzip($string, \$out, Minimal => 1) ) + { + $Compress::Zlib::gzerrno = $IO::Compress::Gzip::GzipError; + return undef ; + } + + return $out; +} + +sub _removeGzipHeader($) +{ + my $string = shift ; + + return Z_DATA_ERROR() + if length($$string) < GZIP_MIN_HEADER_SIZE ; + + my ($magic1, $magic2, $method, $flags, $time, $xflags, $oscode) = + unpack ('CCCCVCC', $$string); + + return Z_DATA_ERROR() + unless $magic1 == GZIP_ID1 and $magic2 == GZIP_ID2 and + $method == Z_DEFLATED() and !($flags & GZIP_FLG_RESERVED) ; + substr($$string, 0, GZIP_MIN_HEADER_SIZE) = '' ; + + # skip extra field + if ($flags & GZIP_FLG_FEXTRA) + { + return Z_DATA_ERROR() + if length($$string) < GZIP_FEXTRA_HEADER_SIZE ; + + my ($extra_len) = unpack ('v', $$string); + $extra_len += GZIP_FEXTRA_HEADER_SIZE; + return Z_DATA_ERROR() + if length($$string) < $extra_len ; + + substr($$string, 0, $extra_len) = ''; + } + + # skip orig name + if ($flags & GZIP_FLG_FNAME) + { + my $name_end = index ($$string, GZIP_NULL_BYTE); + return Z_DATA_ERROR() + if $name_end == -1 ; + substr($$string, 0, $name_end + 1) = ''; + } + + # skip comment + if ($flags & GZIP_FLG_FCOMMENT) + { + my $comment_end = index ($$string, GZIP_NULL_BYTE); + return Z_DATA_ERROR() + if $comment_end == -1 ; + substr($$string, 0, $comment_end + 1) = ''; + } + + # skip header crc + if ($flags & GZIP_FLG_FHCRC) + { + return Z_DATA_ERROR() + if length ($$string) < GZIP_FHCRC_SIZE ; + substr($$string, 0, GZIP_FHCRC_SIZE) = ''; + } + + return Z_OK(); +} + +sub _ret_gun_error +{ + $Compress::Zlib::gzerrno = $IO::Uncompress::Gunzip::GunzipError; + return undef; +} + + +sub memGunzip($) +{ + # if the buffer isn't a reference, make it one + my $string = (ref $_[0] ? $_[0] : \$_[0]); + + $] >= 5.008 and (utf8::downgrade($$string, 1) + or croak "Wide character in memGunzip"); + + _set_gzerr(0); + + my $status = _removeGzipHeader($string) ; + $status == Z_OK() + or return _set_gzerr_undef($status); + + my $bufsize = length $$string > 4096 ? length $$string : 4096 ; + my $x = new Compress::Raw::Zlib::Inflate({-WindowBits => - MAX_WBITS(), + -Bufsize => $bufsize}) + + or return _ret_gun_error(); + + my $output = "" ; + $status = $x->inflate($string, $output); + + if ( $status == Z_OK() ) + { + _set_gzerr(Z_DATA_ERROR()); + return undef; + } + + return _ret_gun_error() + if ($status != Z_STREAM_END()); + + if (length $$string >= 8) + { + my ($crc, $len) = unpack ("VV", substr($$string, 0, 8)); + substr($$string, 0, 8) = ''; + return _set_gzerr_undef(Z_DATA_ERROR()) + unless $len == length($output) and + $crc == crc32($output); + } + else + { + $$string = ''; + } + + return $output; +} + +# Autoload methods go after __END__, and are processed by the autosplit program. + +1; +__END__ + + +=head1 NAME + +Compress::Zlib - Interface to zlib compression library + +=head1 SYNOPSIS + + use Compress::Zlib ; + + ($d, $status) = deflateInit( [OPT] ) ; + $status = $d->deflate($input, $output) ; + $status = $d->flush([$flush_type]) ; + $d->deflateParams(OPTS) ; + $d->deflateTune(OPTS) ; + $d->dict_adler() ; + $d->crc32() ; + $d->adler32() ; + $d->total_in() ; + $d->total_out() ; + $d->msg() ; + $d->get_Strategy(); + $d->get_Level(); + $d->get_BufSize(); + + ($i, $status) = inflateInit( [OPT] ) ; + $status = $i->inflate($input, $output [, $eof]) ; + $status = $i->inflateSync($input) ; + $i->dict_adler() ; + $d->crc32() ; + $d->adler32() ; + $i->total_in() ; + $i->total_out() ; + $i->msg() ; + $d->get_BufSize(); + + $dest = compress($source) ; + $dest = uncompress($source) ; + + $gz = gzopen($filename or filehandle, $mode) ; + $bytesread = $gz->gzread($buffer [,$size]) ; + $bytesread = $gz->gzreadline($line) ; + $byteswritten = $gz->gzwrite($buffer) ; + $status = $gz->gzflush($flush) ; + $offset = $gz->gztell() ; + $status = $gz->gzseek($offset, $whence) ; + $status = $gz->gzclose() ; + $status = $gz->gzeof() ; + $status = $gz->gzsetparams($level, $strategy) ; + $errstring = $gz->gzerror() ; + $gzerrno + + $dest = Compress::Zlib::memGzip($buffer) ; + $dest = Compress::Zlib::memGunzip($buffer) ; + + $crc = adler32($buffer [,$crc]) ; + $crc = crc32($buffer [,$crc]) ; + + $crc = adler32_combine($crc1, $crc2, $len2)l + $crc = crc32_combine($adler1, $adler2, $len2) + + my $version = Compress::Raw::Zlib::zlib_version(); + +=head1 DESCRIPTION + +The I<Compress::Zlib> module provides a Perl interface to the I<zlib> +compression library (see L</AUTHOR> for details about where to get +I<zlib>). + +The C<Compress::Zlib> module can be split into two general areas of +functionality, namely a simple read/write interface to I<gzip> files +and a low-level in-memory compression/decompression interface. + +Each of these areas will be discussed in the following sections. + +=head2 Notes for users of Compress::Zlib version 1 + +The main change in C<Compress::Zlib> version 2.x is that it does not now +interface directly to the zlib library. Instead it uses the +C<IO::Compress::Gzip> and C<IO::Uncompress::Gunzip> modules for +reading/writing gzip files, and the C<Compress::Raw::Zlib> module for some +low-level zlib access. + +The interface provided by version 2 of this module should be 100% backward +compatible with version 1. If you find a difference in the expected +behaviour please contact the author (See L</AUTHOR>). See L<GZIP INTERFACE> + +With the creation of the C<IO::Compress> and C<IO::Uncompress> modules no +new features are planned for C<Compress::Zlib> - the new modules do +everything that C<Compress::Zlib> does and then some. Development on +C<Compress::Zlib> will be limited to bug fixes only. + +If you are writing new code, your first port of call should be one of the +new C<IO::Compress> or C<IO::Uncompress> modules. + +=head1 GZIP INTERFACE + +A number of functions are supplied in I<zlib> for reading and writing +I<gzip> files that conform to RFC 1952. This module provides an interface +to most of them. + +If you have previously used C<Compress::Zlib> 1.x, the following +enhancements/changes have been made to the C<gzopen> interface: + +=over 5 + +=item 1 + +If you want to to open either STDIN or STDOUT with C<gzopen>, you can now +optionally use the special filename "C<->" as a synonym for C<\*STDIN> and +C<\*STDOUT>. + +=item 2 + +In C<Compress::Zlib> version 1.x, C<gzopen> used the zlib library to open +the underlying file. This made things especially tricky when a Perl +filehandle was passed to C<gzopen>. Behind the scenes the numeric C file +descriptor had to be extracted from the Perl filehandle and this passed to +the zlib library. + +Apart from being non-portable to some operating systems, this made it +difficult to use C<gzopen> in situations where you wanted to extract/create +a gzip data stream that is embedded in a larger file, without having to +resort to opening and closing the file multiple times. + +It also made it impossible to pass a perl filehandle that wasn't associated +with a real filesystem file, like, say, an C<IO::String>. + +In C<Compress::Zlib> version 2.x, the C<gzopen> interface has been +completely rewritten to use the L<IO::Compress::Gzip|IO::Compress::Gzip> +for writing gzip files and L<IO::Uncompress::Gunzip|IO::Uncompress::Gunzip> +for reading gzip files. None of the limitations mentioned above apply. + +=item 3 + +Addition of C<gzseek> to provide a restricted C<seek> interface. + +=item 4. + +Added C<gztell>. + +=back + +A more complete and flexible interface for reading/writing gzip +files/buffers is included with the module C<IO-Compress-Zlib>. See +L<IO::Compress::Gzip|IO::Compress::Gzip> and +L<IO::Uncompress::Gunzip|IO::Uncompress::Gunzip> for more details. + +=over 5 + +=item B<$gz = gzopen($filename, $mode)> + +=item B<$gz = gzopen($filehandle, $mode)> + +This function opens either the I<gzip> file C<$filename> for reading or +writing or attaches to the opened filehandle, C<$filehandle>. +It returns an object on success and C<undef> on failure. + +When writing a gzip file this interface will I<always> create the smallest +possible gzip header (exactly 10 bytes). If you want greater control over +what gets stored in the gzip header (like the original filename or a +comment) use L<IO::Compress::Gzip|IO::Compress::Gzip> instead. Similarly if +you want to read the contents of the gzip header use +L<IO::Uncompress::Gunzip|IO::Uncompress::Gunzip>. + +The second parameter, C<$mode>, is used to specify whether the file is +opened for reading or writing and to optionally specify a compression +level and compression strategy when writing. The format of the C<$mode> +parameter is similar to the mode parameter to the 'C' function C<fopen>, +so "rb" is used to open for reading, "wb" for writing and "ab" for +appending (writing at the end of the file). + +To specify a compression level when writing, append a digit between 0 +and 9 to the mode string -- 0 means no compression and 9 means maximum +compression. +If no compression level is specified Z_DEFAULT_COMPRESSION is used. + +To specify the compression strategy when writing, append 'f' for filtered +data, 'h' for Huffman only compression, or 'R' for run-length encoding. +If no strategy is specified Z_DEFAULT_STRATEGY is used. + +So, for example, "wb9" means open for writing with the maximum compression +using the default strategy and "wb4R" means open for writing with compression +level 4 and run-length encoding. + +Refer to the I<zlib> documentation for the exact format of the C<$mode> +parameter. + +=item B<$bytesread = $gz-E<gt>gzread($buffer [, $size]) ;> + +Reads C<$size> bytes from the compressed file into C<$buffer>. If +C<$size> is not specified, it will default to 4096. If the scalar +C<$buffer> is not large enough, it will be extended automatically. + +Returns the number of bytes actually read. On EOF it returns 0 and in +the case of an error, -1. + +=item B<$bytesread = $gz-E<gt>gzreadline($line) ;> + +Reads the next line from the compressed file into C<$line>. + +Returns the number of bytes actually read. On EOF it returns 0 and in +the case of an error, -1. + +It is legal to intermix calls to C<gzread> and C<gzreadline>. + +To maintain backward compatibility with version 1.x of this module +C<gzreadline> ignores the C<$/> variable - it I<always> uses the string +C<"\n"> as the line delimiter. + +If you want to read a gzip file a line at a time and have it respect the +C<$/> variable (or C<$INPUT_RECORD_SEPARATOR>, or C<$RS> when C<English> is +in use) see L<IO::Uncompress::Gunzip|IO::Uncompress::Gunzip>. + +=item B<$byteswritten = $gz-E<gt>gzwrite($buffer) ;> + +Writes the contents of C<$buffer> to the compressed file. Returns the +number of bytes actually written, or 0 on error. + +=item B<$status = $gz-E<gt>gzflush($flush_type) ;> + +Flushes all pending output into the compressed file. + +This method takes an optional parameter, C<$flush_type>, that controls +how the flushing will be carried out. By default the C<$flush_type> +used is C<Z_FINISH>. Other valid values for C<$flush_type> are +C<Z_NO_FLUSH>, C<Z_SYNC_FLUSH>, C<Z_FULL_FLUSH> and C<Z_BLOCK>. It is +strongly recommended that you only set the C<flush_type> parameter if +you fully understand the implications of what it does - overuse of C<flush> +can seriously degrade the level of compression achieved. See the C<zlib> +documentation for details. + +Returns 0 on success. + +=item B<$offset = $gz-E<gt>gztell() ;> + +Returns the uncompressed file offset. + +=item B<$status = $gz-E<gt>gzseek($offset, $whence) ;> + +Provides a sub-set of the C<seek> functionality, with the restriction +that it is only legal to seek forward in the compressed file. +It is a fatal error to attempt to seek backward. + +When opened for writing, empty parts of the file will have NULL (0x00) +bytes written to them. + +The C<$whence> parameter should be one of SEEK_SET, SEEK_CUR or SEEK_END. + +Returns 1 on success, 0 on failure. + +=item B<$gz-E<gt>gzclose> + +Closes the compressed file. Any pending data is flushed to the file +before it is closed. + +Returns 0 on success. + +=item B<$gz-E<gt>gzsetparams($level, $strategy> + +Change settings for the deflate stream C<$gz>. + +The list of the valid options is shown below. Options not specified +will remain unchanged. + +Note: This method is only available if you are running zlib 1.0.6 or better. + +=over 5 + +=item B<$level> + +Defines the compression level. Valid values are 0 through 9, +C<Z_NO_COMPRESSION>, C<Z_BEST_SPEED>, C<Z_BEST_COMPRESSION>, and +C<Z_DEFAULT_COMPRESSION>. + +=item B<$strategy> + +Defines the strategy used to tune the compression. The valid values are +C<Z_DEFAULT_STRATEGY>, C<Z_FILTERED> and C<Z_HUFFMAN_ONLY>. + +=back + +=item B<$gz-E<gt>gzerror> + +Returns the I<zlib> error message or number for the last operation +associated with C<$gz>. The return value will be the I<zlib> error +number when used in a numeric context and the I<zlib> error message +when used in a string context. The I<zlib> error number constants, +shown below, are available for use. + + Z_OK + Z_STREAM_END + Z_ERRNO + Z_STREAM_ERROR + Z_DATA_ERROR + Z_MEM_ERROR + Z_BUF_ERROR + +=item B<$gzerrno> + +The C<$gzerrno> scalar holds the error code associated with the most +recent I<gzip> routine. Note that unlike C<gzerror()>, the error is +I<not> associated with a particular file. + +As with C<gzerror()> it returns an error number in numeric context and +an error message in string context. Unlike C<gzerror()> though, the +error message will correspond to the I<zlib> message when the error is +associated with I<zlib> itself, or the UNIX error message when it is +not (i.e. I<zlib> returned C<Z_ERRORNO>). + +As there is an overlap between the error numbers used by I<zlib> and +UNIX, C<$gzerrno> should only be used to check for the presence of +I<an> error in numeric context. Use C<gzerror()> to check for specific +I<zlib> errors. The I<gzcat> example below shows how the variable can +be used safely. + +=back + +=head2 Examples + +Here is an example script which uses the interface. It implements a +I<gzcat> function. + + use strict ; + use warnings ; + + use Compress::Zlib ; + + # use stdin if no files supplied + @ARGV = '-' unless @ARGV ; + + foreach my $file (@ARGV) { + my $buffer ; + + my $gz = gzopen($file, "rb") + or die "Cannot open $file: $gzerrno\n" ; + + print $buffer while $gz->gzread($buffer) > 0 ; + + die "Error reading from $file: $gzerrno" . ($gzerrno+0) . "\n" + if $gzerrno != Z_STREAM_END ; + + $gz->gzclose() ; + } + +Below is a script which makes use of C<gzreadline>. It implements a +very simple I<grep> like script. + + use strict ; + use warnings ; + + use Compress::Zlib ; + + die "Usage: gzgrep pattern [file...]\n" + unless @ARGV >= 1; + + my $pattern = shift ; + + # use stdin if no files supplied + @ARGV = '-' unless @ARGV ; + + foreach my $file (@ARGV) { + my $gz = gzopen($file, "rb") + or die "Cannot open $file: $gzerrno\n" ; + + while ($gz->gzreadline($_) > 0) { + print if /$pattern/ ; + } + + die "Error reading from $file: $gzerrno\n" + if $gzerrno != Z_STREAM_END ; + + $gz->gzclose() ; + } + +This script, I<gzstream>, does the opposite of the I<gzcat> script +above. It reads from standard input and writes a gzip data stream to +standard output. + + use strict ; + use warnings ; + + use Compress::Zlib ; + + binmode STDOUT; # gzopen only sets it on the fd + + my $gz = gzopen(\*STDOUT, "wb") + or die "Cannot open stdout: $gzerrno\n" ; + + while (<>) { + $gz->gzwrite($_) + or die "error writing: $gzerrno\n" ; + } + + $gz->gzclose ; + +=head2 Compress::Zlib::memGzip + +This function is used to create an in-memory gzip file with the minimum +possible gzip header (exactly 10 bytes). + + $dest = Compress::Zlib::memGzip($buffer) + or die "Cannot compress: $gzerrno\n"; + +If successful, it returns the in-memory gzip file. Otherwise it returns +C<undef> and the C<$gzerrno> variable will store the zlib error code. + +The C<$buffer> parameter can either be a scalar or a scalar reference. + +See L<IO::Compress::Gzip|IO::Compress::Gzip> for an alternative way to +carry out in-memory gzip compression. + +=head2 Compress::Zlib::memGunzip + +This function is used to uncompress an in-memory gzip file. + + $dest = Compress::Zlib::memGunzip($buffer) + or die "Cannot uncomprss: $gzerrno\n"; + +If successful, it returns the uncompressed gzip file. Otherwise it +returns C<undef> and the C<$gzerrno> variable will store the zlib error +code. + +The C<$buffer> parameter can either be a scalar or a scalar reference. The +contents of the C<$buffer> parameter are destroyed after calling this function. + +If C<$buffer> consists of multiple concatenated gzip data streams only the +first will be uncompressed. Use C<gunzip> with the C<MultiStream> option in +the C<IO::Uncompress::Gunzip> module if you need to deal with concatenated +data streams. + +See L<IO::Uncompress::Gunzip|IO::Uncompress::Gunzip> for an alternative way +to carry out in-memory gzip uncompression. + +=head1 COMPRESS/UNCOMPRESS + +Two functions are provided to perform in-memory compression/uncompression of +RFC 1950 data streams. They are called C<compress> and C<uncompress>. + +=over 5 + +=item B<$dest = compress($source [, $level] ) ;> + +Compresses C<$source>. If successful it returns the compressed +data. Otherwise it returns I<undef>. + +The source buffer, C<$source>, can either be a scalar or a scalar +reference. + +The C<$level> parameter defines the compression level. Valid values are +0 through 9, C<Z_NO_COMPRESSION>, C<Z_BEST_SPEED>, +C<Z_BEST_COMPRESSION>, and C<Z_DEFAULT_COMPRESSION>. +If C<$level> is not specified C<Z_DEFAULT_COMPRESSION> will be used. + +=item B<$dest = uncompress($source) ;> + +Uncompresses C<$source>. If successful it returns the uncompressed +data. Otherwise it returns I<undef>. + +The source buffer can either be a scalar or a scalar reference. + +=back + +Please note: the two functions defined above are I<not> compatible with +the Unix commands of the same name. + +See L<IO::Deflate|IO::Deflate> and L<IO::Inflate|IO::Inflate> included with +this distribution for an alternative interface for reading/writing RFC 1950 +files/buffers. + +=head1 Deflate Interface + +This section defines an interface that allows in-memory compression using +the I<deflate> interface provided by zlib. + +Here is a definition of the interface available: + +=head2 B<($d, $status) = deflateInit( [OPT] )> + +Initialises a deflation stream. + +It combines the features of the I<zlib> functions C<deflateInit>, +C<deflateInit2> and C<deflateSetDictionary>. + +If successful, it will return the initialised deflation stream, C<$d> +and C<$status> of C<Z_OK> in a list context. In scalar context it +returns the deflation stream, C<$d>, only. + +If not successful, the returned deflation stream (C<$d>) will be +I<undef> and C<$status> will hold the exact I<zlib> error code. + +The function optionally takes a number of named options specified as +C<< -Name=>value >> pairs. This allows individual options to be +tailored without having to specify them all in the parameter list. + +For backward compatibility, it is also possible to pass the parameters +as a reference to a hash containing the name=>value pairs. + +The function takes one optional parameter, a reference to a hash. The +contents of the hash allow the deflation interface to be tailored. + +Here is a list of the valid options: + +=over 5 + +=item B<-Level> + +Defines the compression level. Valid values are 0 through 9, +C<Z_NO_COMPRESSION>, C<Z_BEST_SPEED>, C<Z_BEST_COMPRESSION>, and +C<Z_DEFAULT_COMPRESSION>. + +The default is Z_DEFAULT_COMPRESSION. + +=item B<-Method> + +Defines the compression method. The only valid value at present (and +the default) is Z_DEFLATED. + +=item B<-WindowBits> + +To create an RFC 1950 data stream, set C<WindowBits> to a positive number. + +To create an RFC 1951 data stream, set C<WindowBits> to C<-MAX_WBITS>. + +For a full definition of the meaning and valid values for C<WindowBits> refer +to the I<zlib> documentation for I<deflateInit2>. + +Defaults to MAX_WBITS. + +=item B<-MemLevel> + +For a definition of the meaning and valid values for C<MemLevel> +refer to the I<zlib> documentation for I<deflateInit2>. + +Defaults to MAX_MEM_LEVEL. + +=item B<-Strategy> + +Defines the strategy used to tune the compression. The valid values are +C<Z_DEFAULT_STRATEGY>, C<Z_FILTERED> and C<Z_HUFFMAN_ONLY>. + +The default is Z_DEFAULT_STRATEGY. + +=item B<-Dictionary> + +When a dictionary is specified I<Compress::Zlib> will automatically +call C<deflateSetDictionary> directly after calling C<deflateInit>. The +Adler32 value for the dictionary can be obtained by calling the method +C<$d->dict_adler()>. + +The default is no dictionary. + +=item B<-Bufsize> + +Sets the initial size for the deflation buffer. If the buffer has to be +reallocated to increase the size, it will grow in increments of +C<Bufsize>. + +The default is 4096. + +=back + +Here is an example of using the C<deflateInit> optional parameter list +to override the default buffer size and compression level. All other +options will take their default values. + + deflateInit( -Bufsize => 300, + -Level => Z_BEST_SPEED ) ; + +=head2 B<($out, $status) = $d-E<gt>deflate($buffer)> + +Deflates the contents of C<$buffer>. The buffer can either be a scalar +or a scalar reference. When finished, C<$buffer> will be +completely processed (assuming there were no errors). If the deflation +was successful it returns the deflated output, C<$out>, and a status +value, C<$status>, of C<Z_OK>. + +On error, C<$out> will be I<undef> and C<$status> will contain the +I<zlib> error code. + +In a scalar context C<deflate> will return C<$out> only. + +As with the I<deflate> function in I<zlib>, it is not necessarily the +case that any output will be produced by this method. So don't rely on +the fact that C<$out> is empty for an error test. + +=head2 B<($out, $status) = $d-E<gt>flush()> +=head2 B<($out, $status) = $d-E<gt>flush($flush_type)> + +Typically used to finish the deflation. Any pending output will be +returned via C<$out>. +C<$status> will have a value C<Z_OK> if successful. + +In a scalar context C<flush> will return C<$out> only. + +Note that flushing can seriously degrade the compression ratio, so it +should only be used to terminate a decompression (using C<Z_FINISH>) or +when you want to create a I<full flush point> (using C<Z_FULL_FLUSH>). + +By default the C<flush_type> used is C<Z_FINISH>. Other valid values +for C<flush_type> are C<Z_NO_FLUSH>, C<Z_PARTIAL_FLUSH>, C<Z_SYNC_FLUSH> +and C<Z_FULL_FLUSH>. It is strongly recommended that you only set the +C<flush_type> parameter if you fully understand the implications of +what it does. See the C<zlib> documentation for details. + +=head2 B<$status = $d-E<gt>deflateParams([OPT])> + +Change settings for the deflate stream C<$d>. + +The list of the valid options is shown below. Options not specified +will remain unchanged. + +=over 5 + +=item B<-Level> + +Defines the compression level. Valid values are 0 through 9, +C<Z_NO_COMPRESSION>, C<Z_BEST_SPEED>, C<Z_BEST_COMPRESSION>, and +C<Z_DEFAULT_COMPRESSION>. + +=item B<-Strategy> + +Defines the strategy used to tune the compression. The valid values are +C<Z_DEFAULT_STRATEGY>, C<Z_FILTERED> and C<Z_HUFFMAN_ONLY>. + +=back + +=head2 B<$d-E<gt>dict_adler()> + +Returns the adler32 value for the dictionary. + +=head2 B<$d-E<gt>msg()> + +Returns the last error message generated by zlib. + +=head2 B<$d-E<gt>total_in()> + +Returns the total number of bytes uncompressed bytes input to deflate. + +=head2 B<$d-E<gt>total_out()> + +Returns the total number of compressed bytes output from deflate. + +=head2 Example + +Here is a trivial example of using C<deflate>. It simply reads standard +input, deflates it and writes it to standard output. + + use strict ; + use warnings ; + + use Compress::Zlib ; + + binmode STDIN; + binmode STDOUT; + my $x = deflateInit() + or die "Cannot create a deflation stream\n" ; + + my ($output, $status) ; + while (<>) + { + ($output, $status) = $x->deflate($_) ; + + $status == Z_OK + or die "deflation failed\n" ; + + print $output ; + } + + ($output, $status) = $x->flush() ; + + $status == Z_OK + or die "deflation failed\n" ; + + print $output ; + +=head1 Inflate Interface + +This section defines the interface available that allows in-memory +uncompression using the I<deflate> interface provided by zlib. + +Here is a definition of the interface: + +=head2 B<($i, $status) = inflateInit()> + +Initialises an inflation stream. + +In a list context it returns the inflation stream, C<$i>, and the +I<zlib> status code in C<$status>. In a scalar context it returns the +inflation stream only. + +If successful, C<$i> will hold the inflation stream and C<$status> will +be C<Z_OK>. + +If not successful, C<$i> will be I<undef> and C<$status> will hold the +I<zlib> error code. + +The function optionally takes a number of named options specified as +C<< -Name=>value >> pairs. This allows individual options to be +tailored without having to specify them all in the parameter list. + +For backward compatibility, it is also possible to pass the parameters +as a reference to a hash containing the name=>value pairs. + +The function takes one optional parameter, a reference to a hash. The +contents of the hash allow the deflation interface to be tailored. + +Here is a list of the valid options: + +=over 5 + +=item B<-WindowBits> + +To uncompress an RFC 1950 data stream, set C<WindowBits> to a positive number. + +To uncompress an RFC 1951 data stream, set C<WindowBits> to C<-MAX_WBITS>. + +For a full definition of the meaning and valid values for C<WindowBits> refer +to the I<zlib> documentation for I<inflateInit2>. + +Defaults to MAX_WBITS. + +=item B<-Bufsize> + +Sets the initial size for the inflation buffer. If the buffer has to be +reallocated to increase the size, it will grow in increments of +C<Bufsize>. + +Default is 4096. + +=item B<-Dictionary> + +The default is no dictionary. + +=back + +Here is an example of using the C<inflateInit> optional parameter to +override the default buffer size. + + inflateInit( -Bufsize => 300 ) ; + +=head2 B<($out, $status) = $i-E<gt>inflate($buffer)> + +Inflates the complete contents of C<$buffer>. The buffer can either be +a scalar or a scalar reference. + +Returns C<Z_OK> if successful and C<Z_STREAM_END> if the end of the +compressed data has been successfully reached. +If not successful, C<$out> will be I<undef> and C<$status> will hold +the I<zlib> error code. + +The C<$buffer> parameter is modified by C<inflate>. On completion it +will contain what remains of the input buffer after inflation. This +means that C<$buffer> will be an empty string when the return status is +C<Z_OK>. When the return status is C<Z_STREAM_END> the C<$buffer> +parameter will contains what (if anything) was stored in the input +buffer after the deflated data stream. + +This feature is useful when processing a file format that encapsulates +a compressed data stream (e.g. gzip, zip). + +=head2 B<$status = $i-E<gt>inflateSync($buffer)> + +Scans C<$buffer> until it reaches either a I<full flush point> or the +end of the buffer. + +If a I<full flush point> is found, C<Z_OK> is returned and C<$buffer> +will be have all data up to the flush point removed. This can then be +passed to the C<deflate> method. + +Any other return code means that a flush point was not found. If more +data is available, C<inflateSync> can be called repeatedly with more +compressed data until the flush point is found. + +=head2 B<$i-E<gt>dict_adler()> + +Returns the adler32 value for the dictionary. + +=head2 B<$i-E<gt>msg()> + +Returns the last error message generated by zlib. + +=head2 B<$i-E<gt>total_in()> + +Returns the total number of bytes compressed bytes input to inflate. + +=head2 B<$i-E<gt>total_out()> + +Returns the total number of uncompressed bytes output from inflate. + +=head2 Example + +Here is an example of using C<inflate>. + + use strict ; + use warnings ; + + use Compress::Zlib ; + + my $x = inflateInit() + or die "Cannot create a inflation stream\n" ; + + my $input = '' ; + binmode STDIN; + binmode STDOUT; + + my ($output, $status) ; + while (read(STDIN, $input, 4096)) + { + ($output, $status) = $x->inflate(\$input) ; + + print $output + if $status == Z_OK or $status == Z_STREAM_END ; + + last if $status != Z_OK ; + } + + die "inflation failed\n" + unless $status == Z_STREAM_END ; + +=head1 CHECKSUM FUNCTIONS + +Two functions are provided by I<zlib> to calculate checksums. For the +Perl interface, the order of the two parameters in both functions has +been reversed. This allows both running checksums and one off +calculations to be done. + + $crc = adler32($buffer [,$crc]) ; + $crc = crc32($buffer [,$crc]) ; + +The buffer parameters can either be a scalar or a scalar reference. + +If the $crc parameters is C<undef>, the crc value will be reset. + +If you have built this module with zlib 1.2.3 or better, two more +CRC-related functions are available. + + $crc = adler32_combine($crc1, $crc2, $len2)l + $crc = crc32_combine($adler1, $adler2, $len2) + +These functions allow checksums to be merged. + +=head1 Misc + +=head2 my $version = Compress::Zlib::zlib_version(); + +Returns the version of the zlib library. + +=head1 CONSTANTS + +All the I<zlib> constants are automatically imported when you make use +of I<Compress::Zlib>. + +=head1 SEE ALSO + +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> + +L<Compress::Zlib::FAQ|Compress::Zlib::FAQ> + +L<File::GlobMapper|File::GlobMapper>, L<Archive::Zip|Archive::Zip>, +L<Archive::Tar|Archive::Tar>, +L<IO::Zlib|IO::Zlib> + +For RFC 1950, 1951 and 1952 see +F<http://www.faqs.org/rfcs/rfc1950.html>, +F<http://www.faqs.org/rfcs/rfc1951.html> and +F<http://www.faqs.org/rfcs/rfc1952.html> + +The I<zlib> compression library was written by Jean-loup Gailly +F<gzip@prep.ai.mit.edu> and Mark Adler F<madler@alumni.caltech.edu>. + +The primary site for the I<zlib> compression library is +F<http://www.zlib.org>. + +The primary site for gzip is F<http://www.gzip.org>. + +=head1 AUTHOR + +This module was written by Paul Marquess, F<pmqs@cpan.org>. + +=head1 MODIFICATION HISTORY + +See the Changes file. + +=head1 COPYRIGHT AND LICENSE + +Copyright (c) 1995-2010 Paul Marquess. All rights reserved. + +This program is free software; you can redistribute it and/or +modify it under the same terms as Perl itself. + diff --git a/Master/tlpkg/tlperl/lib/Compress/unLZMA.pm b/Master/tlpkg/tlperl/lib/Compress/unLZMA.pm new file mode 100755 index 00000000000..dc7d4c95a8a --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Compress/unLZMA.pm @@ -0,0 +1,158 @@ +package Compress::unLZMA; + +use strict; +use warnings; + +require Exporter; + +our @ISA = qw(Exporter); + +our %EXPORT_TAGS = ( 'all' => [ qw( + uncompress uncompressfile +) ] ); + +our @EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} } ); + +our $VERSION = '0.03'; + +require XSLoader; +XSLoader::load('Compress::unLZMA', $VERSION); + +sub compress { + die "not implemented!\n"; +} + +sub compressfile { + die "not implemented!\n"; +} + +sub uncompress { + my ($data) = @_; + + return undef if (length($data) < 14); + + my $properties = substr($data, 0, 5); + + my $size = 0; + for (my $ii = 0; $ii < 4; $ii++) { + my $b = ord(substr($data, $ii + 5, 1)); + $size += $b << ($ii * 8); + } + + for (my $ii = 0; $ii < 4; $ii++) { + my $b = ord(substr($data, $ii + 9, 1)); + if ($b != 0) { + return undef; + } + } + + if (ord(substr($properties, 0, 1)) >= (9 * 5 * 5)) { + return undef; + } + + if ( $size == 0 ) { # empty file: no data to uncompress + return ''; + } + + $data = substr($data, 13); + + my $result = uncompressdata($data, length($data), $size, $properties); + + return $result; +} + +1; + +__END__ + +=head1 NAME + +Compress::unLZMA - Interface to LZMA decompression library + +=head1 SYNOPSIS + + use Compress::unLZMA qw(uncompress uncompressfile); + my $data = uncompressfile('foo.lzma'); + my $data = uncompress($content); + +=head1 DESCRIPTION + +LZMA is default and general compression method of 7z format +in 7-Zip program. LZMA provides high compression ratio and very +fast decompression. + +This module is based on the LZMA SDK which provides a cross-platform +implementation of the LZMA decompression algorithm in ANSI C. + +From SDK lzma.txt file: + + LZMA decompression code was ported from original C++ sources to C. + Also it was simplified and optimized for code size. + But it is fully compatible with LZMA from 7-Zip. + +=head1 METHODS + +=over 4 + +=item $data = uncompress($content) + +Uncompress $data. if successfull, it returns the uncompressed data. +Otherwise it returns undef and $@ contains the error message. + +The source buffer can be either be a scalar or a scalar reference. + +=item $data = uncompressfile($file) + +Uncompress the file $file. if successfull, it returns the uncompressed data. +Otherwise it returns undef and $@ contains the error message. + +=back + +=head1 CAVEATS + +This version only implements in-memory decompression (patches are welcomed). + +There is no way to recognize a valid LZMA encoded file with the SDK. +So, in some cases, you can crash your script if you try to uncompress +a non valid LZMA encoded file. + +=head1 REQUESTS & BUGS + +Please report any requests, suggestions or bugs via the RT bug-tracking system +at http://rt.cpan.org/ or email to bug-Compress-unLZMA\@rt.cpan.org. + +http://rt.cpan.org/NoAuth/Bugs.html?Dist=Compress-unLZMA is the RT queue for Compress::unLZMA. +Please check to see if your bug has already been reported. + +=head1 MAINTAINER + +Adriano Ferreira, ferreira@cpan.org + +=head1 COPYRIGHT + +Copyright 2004 + +Fabien Potencier, fabpot@cpan.org + +This software may be freely copied and distributed under the same +terms and conditions as Perl. + +=head1 LZMA COPYRIGHT + +LZMA SDK 4.01 Copyright (C) 1999-2004 Igor Pavlov 2004-02-15 + +This library is free software; you can redistribute it and/or +modify it under the terms of the GNU Lesser General Public +License as published by the Free Software Foundation; either +version 2.1 of the License, or (at your option) any later version. + +LZMA SDK also can be available under a proprietary license for +those who cannot use the GNU LGPL in their code. To request +such proprietary license or any additional consultations, +write to support@7-zip.org + +=head1 SEE ALSO + +perl(1), http://www.7-zip.org/. + +=cut |