NAME

Compress::Raw::Lzma - Low-Level Interface to lzma compression library

SYNOPSIS

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::bzlibversion();

DESCRIPTION

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.

Compression

There are four compression interfaces available in this module.

Compress::Raw::Lzma::EasyEncoder =item Compress::Raw::Lzma::AloneEncoder =item Compress::Raw::Lzma::StreamEncoder =item Compress::Raw::Lzma::RawEncoder

($z, $status) = new Compress::Raw::Lzma::EasyEncoder [OPTS];

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:

Preset => $preset

Valid values are 0-9 and LZMA_PRESET_DEFAULT.

Defaults to LZMA_PRESET_DEFAULT.

Extreme => 0|1

Makes the compression a lot slower, but a small compression gain.

Defaults to 0.

Check => $check

Used to specify the integrrity check used in the xz data stream. Valid values are LZMA_CHECK_NONE, LZMA_CHECK_CRC32, LZMA_CHECK_CRC64, LZMA_CHECK_SHA256.

Defaults to LZMA_CHECK_CRC32.

AppendOutput => 0|1

Controls whether the compressed data is appended to the output buffer in the code and flush methods.

Defaults to 1.

BufSize => $number

Sets the initial size for the output buffer used by the $d->code method. If the buffer has to be reallocated to increase the size, it will grow in increments of Bufsize.

Defaults to 16k.

($z, $status) = new Compress::Raw::Lzma::AloneEncoder [OPTS];

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 => $filter

TODO - add something about filters.

AppendOutput => 0|1

Controls whether the compressed data is appended to the output buffer in the code and flush methods.

Defaults to 1.

BufSize => $number

Sets the initial size for the output buffer used by the $d->code method. If the buffer has to be reallocated to increase the size, it will grow in increments of Bufsize.

Defaults to 16k.

($z, $status) = new Compress::Raw::Lzma::StreamEncoder [OPTS];

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:

Filter => $filter

TODO - add something about filters.

Check => $check

Used to specify the integrrity check used in the xz data stream. Valid values are LZMA_CHECK_NONE, LZMA_CHECK_CRC32, LZMA_CHECK_CRC64, LZMA_CHECK_SHA256.

Defaults to LZMA_CHECK_CRC32.

AppendOutput => 0|1

Controls whether the compressed data is appended to the output buffer in the code and flush methods.

Defaults to 1.

BufSize => $number

Sets the initial size for the output buffer used by the $d->code method. If the buffer has to be reallocated to increase the size, it will grow in increments of Bufsize.

Defaults to 16k.

($z, $status) = new Compress::Raw::Lzma::RawEncoder [OPTS];

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:

Filter => $filter

TODO - add something about filters.

AppendOutput => 0|1

Controls whether the compressed data is appended to the output buffer in the code and flush methods.

Defaults to 1.

BufSize => $number

Sets the initial size for the output buffer used by the $d->code method. If the buffer has to be reallocated to increase the size, it will grow in increments of Bufsize.

Defaults to 16k.

$status = $lz->code($input, $output);

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.

$status = $lz->flush($output, LZMA_FINISH);

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.

Example

TODO

Uncompression

There are four uncompression interfaces available in this module.

Compress::Raw::Lzma::AutoDecoder =item Compress::Raw::Lzma::AloneDecoder =item Compress::Raw::Lzma::StreamDecoder =item Compress::Raw::Lzma::RawDecoder

($z, $status) = new Compress::Raw::Lzma::AutoDecoder [OPTS] ;

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:

-MemLimit

The number of bytes to use when uncompressing.

Default is 128Meg.

-Bufsize

Sets the initial size for the output buffer used by the $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.

-AppendOutput

This option controls how data is written to the output buffer by the $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.

-ConsumeInput

If set to true, this option will remove compressed data from the input buffer of the $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

The 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.

($z, $status) = new Compress::Raw::Lzma::AloneDecoder [OPTS] ;

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:

-MemLimit

The number of bytes to use when uncompressing.

Default is 128Meg.

-Bufsize

Sets the initial size for the output buffer used by the $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.

-AppendOutput

This option controls how data is written to the output buffer by the $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.

-ConsumeInput

If set to true, this option will remove compressed data from the input buffer of the $i->code method as the uncompression progresses.

This option defaults to true.

-LimitOutput

The 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 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.

$status = $z->code($input, $output);

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.

Filters

A number of the compression interfaces and the raw uncompression interface make use of filters.

TODO - more here

Misc

my $version = Compress::Raw::Lzma::lzma_version_number();

Returns the version of the underlying lzma library.

my $version = Compress::Raw::Lzma::lzma_version_string();

Returns the version of the underlying lzma library.

TODO - more here

Constants

The following lzma constants are exported by this module

TODO - more here

AUTHOR

This module was written by Paul Marquess, pmqs@cpan.org.

MODIFICATION HISTORY

See the Changes file.

COPYRIGHT AND LICENSE

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

To install Compress::Raw::Lzma, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Compress::Raw::Lzma

CPAN shell

perl -MCPAN -e shell
install Compress::Raw::Lzma

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

Compression

($z, $status) = new Compress::Raw::Lzma::EasyEncoder [OPTS];

($z, $status) = new Compress::Raw::Lzma::AloneEncoder [OPTS];

($z, $status) = new Compress::Raw::Lzma::StreamEncoder [OPTS];

($z, $status) = new Compress::Raw::Lzma::RawEncoder [OPTS];

$status = $lz->code($input, $output);

$status = $lz->flush($output, LZMA_FINISH);

Example

Uncompression

($z, $status) = new Compress::Raw::Lzma::AutoDecoder [OPTS] ;

($z, $status) = new Compress::Raw::Lzma::AloneDecoder [OPTS] ;

$status = $z->code($input, $output);

Filters

Misc

my $version = Compress::Raw::Lzma::lzma_version_number();

my $version = Compress::Raw::Lzma::lzma_version_string();

Constants

SEE ALSO

AUTHOR

MODIFICATION HISTORY

COPYRIGHT AND LICENSE

Module Install Instructions