|
Compress::Raw::Lzma - Low-Level Interface to lzma compression library |
Compress::Raw::Lzma - Low-Level Interface to lzma compression library
use Compress::Raw::Lzma ;
# Encoders
my ($lz, $status) = new Compress::Raw::Lzma::EasyEncoder [OPTS]
or die "Cannot create lzma object: $status\n";
my ($lz, $status) = new Compress::Raw::Lzma::AloneEncoder [OPTS]
or die "Cannot create lzma object: $status\n";
my ($lz, $status) = new Compress::Raw::Lzma::StreamEncoder [OPTS]
or die "Cannot create lzma object: $status\n";
my ($lz, $status) = new Compress::Raw::Lzma::RawEncoder [OPTS]
or die "Cannot create lzma object: $status\n";
$status = $lz->code($input, $output);
$status = $lz->flush($output);
# Decoders
my ($lz, $status) = new Compress::Raw::Lzma::AloneDecoder [OPTS]
or die "Cannot create bunzip2 object: $status\n";
my ($lz, $status) = new Compress::Raw::Lzma::AutoDecoder [OPTS]
or die "Cannot create bunzip2 object: $status\n";
my ($lz, $status) = new Compress::Raw::Lzma::StreamDecoder [OPTS]
or die "Cannot create bunzip2 object: $status\n";
my ($lz, $status) = new Compress::Raw::Lzma::RawDecoder [OPTS]
or die "Cannot create bunzip2 object: $status\n";
$status = $lz->code($input, $output);
my $version = Compress::Raw::Lzma::lzma_version_number();
my $version = Compress::Raw::Lzma::lzma_version_string();
Compress::Raw::Lzma provides an interface to the in-memory
compression/uncompression functions from the lzma compression library.
Although the primary purpose for the existence of Compress::Raw::Lzma is
for use by the IO::Compress::Lzma, IO::Uncompress::UnLzma,
IO::Compress::Xz and IO::Uncompress::UnXz modules, it can be used on
its own for simple compression/uncompression tasks.
There are four compression interfaces available in this module.
Creates a new xz compression object.
If successful, it will return the initialised compression object, $z
and a $status of LZMA_OK in a list context. In scalar context it
returns the deflation object, $z, only.
If not successful, the returned compression object, $z, will be
undef and $status will hold the an lzma error code.
Below is a list of the valid options:
Valid values are 0-9 and LZMA_PRESET_DEFAULT.
0 is the fastest compression with the lowest memory usage and the lowest compression.
9 is the slowest compression with the highest memory usage but with the best compression.
Defaults to LZMA_PRESET_DEFAULT.
Defaults to 0.
LZMA_CHECK_NONE, LZMA_CHECK_CRC32,
LZMA_CHECK_CRC64, LZMA_CHECK_SHA256.
Defaults to LZMA_CHECK_CRC32.
code and flush methods.
Defaults to 1.
$d->code
method. If the buffer has to be reallocated to increase the size, it will
grow in increments of Bufsize.
Defaults to 16k.
Creates a legacy lzma compression object. This format is also know as lzma_alone.
If successful, it will return the initialised compression object, $z
and a $status of LZMA_OK in a list context. In scalar context it
returns the deflation object, $z, only.
If not successful, the returned compression object, $z, will be
undef and $status will hold the an lzma error code.
Below is a list of the valid options:
$filter option must be an object of type Lzma::Filter::Lzma1.
See Lzma::Filter::Lzma in the Compress::Raw::Lzma manpage for a definition
of Lzma::Filter::Lzma1.
If this option is not present an Lzma::Filter::Lzma1 object with default
values will be used.
code and flush methods.
Defaults to 1.
$d->code
method. If the buffer has to be reallocated to increase the size, it will
grow in increments of Bufsize.
Defaults to 16k.
Creates a xz compression object.
If successful, it will return the initialised compression object, $z
and a $status of LZMA_OK in a list context. In scalar context it
returns the deflation object, $z, only.
If not successful, the returned compression object, $z, will be
undef and $status will hold the an lzma error code.
Below is a list of the valid options:
LZMA_FILTERS_MAX filters to the data stream
during compression. See Filters for more details on the available
filters.
If this option is present it must either contain a single
Lzma::Filter::Lzma filter object or an array reference containing between
one and LZMA_FILTERS_MAX filter objects.
If this option is not present an Lzma::Filter::Lzma2 object with default
values will be used.
LZMA_CHECK_NONE, LZMA_CHECK_CRC32,
LZMA_CHECK_CRC64, LZMA_CHECK_SHA256.
Defaults to LZMA_CHECK_CRC32.
code and flush methods.
Defaults to 1.
$d->code
method. If the buffer has to be reallocated to increase the size, it will
grow in increments of Bufsize.
Defaults to 16k.
Low level access to lzma.
If successful, it will return the initialised compression object, $z
and a $status of LZMA_OK in a list context. In scalar context it
returns the deflation object, $z, only.
If not successful, the returned compression object, $z, will be
undef and $status will hold the an lzma error code.
Below is a list of the valid options:
LZMA_FILTERS_MAX filters to the data stream
during compression. See Filters for more details on the available
filters.
If this option is present it must either contain a single
Lzma::Filter::Lzma filter object or an array reference containing between
one and LZMA_FILTERS_MAX filter objects.
If this option is not present an Lzma::Filter::Lzma2 object with default
values will be used.
code and flush methods.
Defaults to 1.
$d->code
method. If the buffer has to be reallocated to increase the size, it will
grow in increments of Bufsize.
Defaults to 16k.
Defaults to 0.
Reads the contents of $input, compresses it and writes the compressed
data to $output.
Returns LZMA_OK on success and an lzma error code on failure.
If appendOutput is enabled in the constructor for the lzma object, the
compressed data will be appended to $output. If not enabled, $output
will be truncated before the compressed data is written to it.
Flushes any pending compressed data to $output. By default it terminates
the compressed data stream.
Returns LZMA_OK on success and an lzma error code on failure.
TODO
There are four uncompression interfaces available in this module.
Create an object that can uncompress any of the compressed data streams that can be created by this module.
If successful, it will return the initialised uncompression object, $z
and a $status of LZMA_OK in a list context. In scalar context it
returns the deflation object, $z, only.
If not successful, the returned uncompression object, $z, will be
undef and $status will hold the an lzma error code.
Below is a list of the valid options:
Default is unlimited.
$i->code
method. If the output buffer in this method has to be reallocated to
increase the size, it will grow in increments of Bufsize.
Default is 16k.
$i->code method.
If the option is set to false, the output buffer in the $i->code
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 $i->code method.
This option defaults to false.
$i->code method as the uncompression 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.
LimitOutput option changes the behavior of the $i->code
method so that the amount of memory used by the output buffer can be
limited.
When LimitOutput is used the size of the output buffer used will either
be the value of the Bufsize option or the amount of memory already
allocated to $output, whichever is larger. Predicting the output size
available is tricky, so don't rely on getting an exact output buffer size.
When LimitOutout is not specified $i->code will use as much
memory as it takes to write all the uncompressed data it creates by
uncompressing the input buffer.
If LimitOutput is enabled, the ConsumeInput option will also be
enabled.
This option defaults to false.
See The LimitOutput option for a discussion on why LimitOutput is
needed and how to use it.
Create an object that can uncompress an lzma_alone data stream.
If successful, it will return the initialised uncompression object, $z
and a $status of LZMA_OK in a list context. In scalar context it
returns the deflation object, $z, only.
If not successful, the returned uncompression object, $z, will be
undef and $status will hold the an lzma error code.
Below is a list of the valid options:
Default is unlimited.
$i->code
method. If the output buffer in this method has to be reallocated to
increase the size, it will grow in increments of Bufsize.
Default is 16k.
$i->code method.
If the option is set to false, the output buffer in the $i->code
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 $i->code method.
This option defaults to false.
$i->code method as the uncompression 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.
LimitOutput option changes the behavior of the $i->code
method so that the amount of memory used by the output buffer can be
limited.
When LimitOutput is used the size of the output buffer used will either
be the value of the Bufsize option or the amount of memory already
allocated to $output, whichever is larger. Predicting the output size
available is tricky, so don't rely on getting an exact output buffer size.
When LimitOutout is not specified $i->code will use as much
memory as it takes to write all the uncompressed data it creates by
uncompressing the input buffer.
If LimitOutput is enabled, the ConsumeInput option will also be
enabled.
This option defaults to false.
See The LimitOutput option for a discussion on why LimitOutput is
needed and how to use it.
Uncompresses $input and writes the uncompressed data to $output.
Returns LZMA_OK if the uncompression was successful, but the end of the
compressed data stream has not been reached. Returns LZMA_STREAM_END on
successful uncompression and the end of the compression stream has been
reached.
If consumeInput is enabled in the constructor for the lzma object,
$input will have all compressed data removed from it after
uncompression. On LZMA_OK return this will mean that $input will be an
empty string; when LZMA_STREAM_END $input will either be an empty
string or will contain whatever data immediately followed the compressed
data stream.
If appendOutput is enabled in the constructor for the lzma object,
the uncompressed data will be appended to $output. If not enabled,
$output will be truncated before the uncompressed data is written to it.
TODO - more here
A number of the Lzma compression interfaces (namely
Compress::Raw::Lzma::StreamEncoder &
Compress::Raw::Lzma::AloneEncoder) and the raw lzma uncompression interface
make use of filters. These filters are used to change the behaviour of
compression (and raw uncompression).
All Lzma Filters are sub-classed from the Lzma::Filter base-class.
The Lzma::Filter::Lzma class is used to... TODO - more here
There are two subclasses of Lzma::Filter::Lzma, namely
Lzma::Filter::Lzma1 and Lzma::Filter::Lzma2.
The former is typically used with Compress::Raw::Lzma::AloneEncoder.
The latter with Compress::Raw::Lzma::StreamEncoder.
When using Lzma filters an Lzma::Filter::Lzma must be included and it
must be the last filter in the chain. There can only be one
Lzma::Filter::Lzma filter in any filter chain.
The Lzma::Filter::Lzma construction takes the following options.
LZMA_DICT_SIZE_MIN.
Defaults to LZMA_DICT_SIZE_DEFAULT.
How many of the highest bits of the previous uncompressed eight-bit byte (also known as `literal') are taken into account when predicting the bits of the next literal.
$value must be a number between LZMA_LCLP_MIN and
LZMA_LCLP_MAX.
Note the sum of the C<Lc> and C<Lp> options cannot exceed 4.
Defaults to LZMA_LC_DEFAULT.
How many of the lowest bits of the current position (number of bytes from the beginning of the uncompressed data) in the uncompressed data is taken into account when predicting the bits of the next literal (a single eight-bit byte).
Defaults to LZMA_LP_DEFAULT.
How many of the lowest bits of the current position in the uncompressed data is taken into account when estimating probabilities of matches. A match is a sequence of bytes for which a matching sequence is found from the dictionary and thus can be stored as distance-length pair.
$value must be a number between LZMA_PB_MIN and
LZMA_PB_MAX.
Defaults to LZMA_PB_DEFAULT.
LZMA_MODE_FAST and
LZMA_MODE_NORMAL.
Defaults to LZMA_MODE_NORMAL.
Defaults to 64.
LZMA_MF_HC3
LZMA_MF_HC4, LZMA_MF_BT2 LZMA_MF_BT3 and LZMA_MF_BT4.
Defaults to LZMA_MF_BT4.
Defaults to 0.
The sub-classes of Lzma::Filter::BCJ are the
Branch/Call/Jump conversion filters. These filters are used to rewrite
executable binary code for a number of processor architectures.
None of these classes take any options.
Usage is
Lzma::Filter::Delta [OPTS]
LZMA_DELTA_TYPE_BYTE,
$value must be a number between
LZMA_DELTA_DIST_MIN and LZMA_DELTA_DIST_MAX.
Default is LZMA_DELTA_DIST_MIN.
Returns the version of the underlying lzma library.
Returns the version of the underlying lzma library.
TODO - more here
The following lzma constants are exported by this module
TODO - more here
the Compress::Zlib manpage, the IO::Compress::Gzip manpage, the IO::Uncompress::Gunzip manpage, the IO::Compress::Deflate manpage, the IO::Uncompress::Inflate manpage, the IO::Compress::RawDeflate manpage, the IO::Uncompress::RawInflate manpage, the IO::Compress::Bzip2 manpage, the IO::Uncompress::Bunzip2 manpage, the IO::Compress::Lzma manpage, the IO::Uncompress::UnLzma manpage, the IO::Compress::Xz manpage, the IO::Uncompress::UnXz manpage, the IO::Compress::Lzop manpage, the IO::Uncompress::UnLzop manpage, the IO::Compress::Lzf manpage, the IO::Uncompress::UnLzf manpage, the IO::Uncompress::AnyInflate manpage, the IO::Uncompress::AnyUncompress manpage
File::GlobMapper, Archive::Zip, Archive::Tar, IO::Zlib
This module was written by Paul Marquess, pmqs@cpan.org.
See the Changes file.
Copyright (c) 2005-2015 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.
|
Compress::Raw::Lzma - Low-Level Interface to lzma compression library |