NAME

Compress::Raw::Lzma - Low-Level Perl 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 lzma object: $status\n";

my ($lz, $status) = new Compress::Raw::Lzma::AutoDecoder [OPTS]
    or die "Cannot create lzma object: $status\n";

my ($lz, $status) = new Compress::Raw::Lzma::StreamDecoder [OPTS]
    or die "Cannot create lzma object: $status\n";

my ($lz, $status) = new Compress::Raw::Lzma::RawDecoder [OPTS]
    or die "Cannot create lzma object: $status\n";

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

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

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.

There are two functions, called code and flush, used in all the compression and uncompression interfaces defined in this module. By default both of these functions overwrites any data stored in its output buffer parameter. If you want to compress/uncompress to a single buffer, and have code and flush append to that buffer, enable the AppendOutput option when you create the compression/decompression object.

Compression

There are four compression interfaces available in this module.

Compress::Raw::Lzma::EasyEncoder
Compress::Raw::Lzma::AloneEncoder
Compress::Raw::Lzma::StreamEncoder
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

Used to choose the compression preset.

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.

Extreme => 0|1

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

Defaults to 0.

Check => $check

Used to specify the integrity 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 0. (Note in versions of this module prior to 2.072 the default value was incorrectly documented as 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

The $filter option must be an object of type Lzma::Filter::Lzma1. See "Lzma::Filter::Lzma" in Compress::Raw::Lzma for a definition of Lzma::Filter::Lzma1.

If this option is not present an Lzma::Filter::Lzma1 object with default values will be used.

AppendOutput => 0|1

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

Defaults to 0. (Note in versions of this module prior to 2.072 the default value was incorrectly documented as 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

Filter => [$filter1, $filter2,...]

This option is used to change the bahaviour of the StreamEncoder by applying between one and 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.

Check => $check

Used to specify the integrity 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 0. (Note in versions of this module prior to 2.072 the default value was incorrectly documented as 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

Filter => [$filter1, $filter2,...]

This option is used to change the bahaviour of the RawEncoder by applying between one and 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.

AppendOutput => 0|1

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

Defaults to 0. (Note in versions of this module prior to 2.072 the default value was incorrectly documented as 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.

ForZip => 1/0

This boolean option is used to enable prefixing the compressed data stream with an encoded copy of the filter properties.

Defaults to 0.

$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_STREAM_END on success and an lzma error code on failure.

Compression examples

Simple compression with EasyEncoder

use strict;
use warnings;

use Compress::Raw::Lzma;

my ($lz, $status) = Compress::Raw::Lzma::EasyEncoder->new(
    Preset => 6,
    Extreme => 0,
);
die "Cannot create encoder: $status\n" unless $lz;

my $input = "This is the data to compress " x 100;
my $compressed = '';

$status = $lz->code($input, $compressed);
die "Compression failed: $status\n" unless $status == LZMA_OK;

$status = $lz->flush($compressed);
die "Flush failed: $status\n" unless $status == LZMA_STREAM_END;

print "Original size: ", length($input), "\n";
print "Compressed size: ", length($compressed), "\n";

Streaming compression with AppendOutput

use strict;
use warnings;

use Compress::Raw::Lzma;

my ($lz, $status) = Compress::Raw::Lzma::EasyEncoder->new(
    AppendOutput => 1,
    Preset => LZMA_PRESET_DEFAULT,
);
die "Cannot create encoder: $status\n" unless $lz;

my $compressed = '';

# Compress data in chunks
for my $chunk ("Hello ", "world", "!") {
    $status = $lz->code($chunk, $compressed);
    die "Compression failed\n" unless $status == LZMA_OK;
}

# Finish compression
$status = $lz->flush($compressed);
die "Flush failed\n" unless $status == LZMA_STREAM_END;

print "Compressed: ", length($compressed), " bytes\n";

Using custom filters with StreamEncoder

use strict;
use warnings;

use Compress::Raw::Lzma;

# Create a custom LZMA2 filter
my $filter = Lzma::Filter::Lzma2(
    DictSize => 1024 * 1024 * 8,  # 8MB dictionary
    Lc => 3,
    Lp => 0,
    Pb => 2,
    Mode => LZMA_MODE_NORMAL,
    Nice => 128,
    Mf => LZMA_MF_BT4,
    Depth => 512,
);

my ($lz, $status) = Compress::Raw::Lzma::StreamEncoder->new(
    Filter => $filter,
    Check => LZMA_CHECK_SHA256,
);
die "Cannot create encoder: $status\n" unless $lz;

my $input = "Custom filter example data";
my $compressed = '';

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

Using multiple filters (BCJ + LZMA2)

use strict;
use warnings;

use Compress::Raw::Lzma;

# Combine BCJ filter for x86 binaries with LZMA2 compression
my @filters = (
    Lzma::Filter::X86(),      # BCJ filter for x86 code
    Lzma::Filter::Lzma2(),    # LZMA2 compression
);

my ($lz, $status) = Compress::Raw::Lzma::StreamEncoder->new(
    Filter => \@filters,
    Check => LZMA_CHECK_CRC64,
);
die "Cannot create encoder: $status\n" unless $lz;

# ... compress binary data ...

Uncompression

There are four uncompression interfaces available in this module.

Compress::Raw::Lzma::AutoDecoder
Compress::Raw::Lzma::AloneDecoder
Compress::Raw::Lzma::StreamDecoder
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 unlimited.

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

($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 unlimited.

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

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

Uncompression examples

Simple uncompression with AutoDecoder

use strict;
use warnings;

use Compress::Raw::Lzma;

# $compressed contains xz/lzma compressed data
my $compressed = ...;

my ($lz, $status) = Compress::Raw::Lzma::AutoDecoder->new(
    AppendOutput => 1,
    ConsumeInput => 1,
);
die "Cannot create decoder: $status\n" unless $lz;

my $uncompressed = '';
$status = $lz->code($compressed, $uncompressed);
die "Decompression failed: $status\n"
    unless $status == LZMA_STREAM_END;

print "Uncompressed size: ", length($uncompressed), "\n";

Streaming uncompression with LimitOutput

use strict;
use warnings;

use Compress::Raw::Lzma;

my ($lz, $status) = Compress::Raw::Lzma::AutoDecoder->new(
    LimitOutput => 1,
    ConsumeInput => 1,
    Bufsize => 4096,
);
die "Cannot create decoder: $status\n" unless $lz;

# Process compressed data in chunks
my $compressed = ...;  # your compressed data
my $uncompressed = '';

while (length($compressed) > 0) {
    my $output = '';
    $status = $lz->code($compressed, $output);

    $uncompressed .= $output;

    last if $status == LZMA_STREAM_END;
    die "Decompression error: $status\n" unless $status == LZMA_OK;
}

print "Total uncompressed: ", length($uncompressed), " bytes\n";

Uncompressing specific format with AloneDecoder

use strict;
use warnings;

use Compress::Raw::Lzma;

# For legacy .lzma format (lzma_alone)
my ($lz, $status) = Compress::Raw::Lzma::AloneDecoder->new(
    MemLimit => 128 * 1024 * 1024,  # 128 MB limit
    AppendOutput => 0,
);
die "Cannot create decoder: $status\n" unless $lz;

my $compressed = ...;  # .lzma format data
my $output = '';

$status = $lz->code($compressed, $output);
die "Decompression failed: $status\n"
    unless $status == LZMA_STREAM_END;

Filters

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.

Lzma::Filter::Lzma

The Lzma::Filter::Lzma class is the primary compression filter for LZMA algorithms. It provides fine-grained control over compression parameters.

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.

DictSize => $value

Dictionary size in bytes. This controls how many bytes of the recently processed uncompressed data is kept in memory. The size of the dictionary must be at least LZMA_DICT_SIZE_MIN.

Defaults to LZMA_DICT_SIZE_DEFAULT.

PresetDict => $dict

Provide an initial dictionary. This value is used to initialize the LZ77 history window.

This feature only works correctly with raw encoding and decoding. You may not be able to decode other formats that have been encoded with a preset dictionary.

$dict should contain typical strings that occur in the files being compressed, with the most probably strings near the end fo the preset dictionary.

If $dict is larger than DictSize, only the last DictSize bytes are processed.

Lc => $value

Number of literal context bits.

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 Lc and Lp options cannot exceed 4.

Defaults to LZMA_LC_DEFAULT.

Lp => $value

Number of literal position bits.

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.

Pb => $value

Number of position bits

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.

Mode => $value

The Compression Mode. Valid values are LZMA_MODE_FAST and LZMA_MODE_NORMAL.

Defaults to LZMA_MODE_NORMAL.

Nice => $value

Nice length of a match

Defaults to 64.

Mf => $value

Defines which Match Finder to use. Valid values are LZMA_MF_HC3 LZMA_MF_HC4, LZMA_MF_BT2 LZMA_MF_BT3 and LZMA_MF_BT4.

Defaults to LZMA_MF_BT4.

Depth => $value

Maximum search depth in the match finder.

Defaults to 0.

Lzma::Filter::BCJ

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.

Lzma::Filter::X86: Filter for x86 binaries.
Lzma::Filter::PowerPC: Filter for Big endian PowerPC binaries.
Lzma::Filter::IA64: Filter for IA64 (Itanium) binaries.
Lzma::Filter::ARM: Filter for ARM binaries.
Lzma::Filter::ARMThumb: Filter for ARMThumb binaries.
Lzma::Filter::Sparc: Filter for Sparc binaries.

Lzma::Filter::Delta

Usage is

Lzma::Filter::Delta [OPTS]

Type => $type

Defines the type of Delta calculation. The only available type (and therefore the default) is LZMA_DELTA_TYPE_BYTE,

Distance => $value

Defines the Delta Distance. $value must be a number between LZMA_DELTA_DIST_MIN and LZMA_DELTA_DIST_MAX.

Default is LZMA_DELTA_DIST_MIN.

Filter examples

Using LZMA2 filter with custom dictionary size

use strict;
use warnings;

use Compress::Raw::Lzma;

# Create LZMA2 filter with large dictionary for better compression
my $filter = Lzma::Filter::Lzma2(
    DictSize => 16 * 1024 * 1024,  # 16 MB dictionary
    Lc => 3,
    Lp => 0,
    Pb => 2,
);

my ($lz, $status) = Compress::Raw::Lzma::StreamEncoder->new(
    Filter => $filter,
    Check => LZMA_CHECK_CRC64,
);
die "Cannot create encoder: $status\n" unless $lz;

my $input = "Data to compress...";
my $output = '';

$lz->code($input, $output);
$lz->flush($output);

Using LZMA1 filter for legacy .lzma format

use strict;
use warnings;

use Compress::Raw::Lzma;

# LZMA1 is used for the legacy .lzma format
my $filter = Lzma::Filter::Lzma1(
    DictSize => 8 * 1024 * 1024,
    Mode => LZMA_MODE_NORMAL,
    Mf => LZMA_MF_BT4,
    Nice => 273,
);

my ($lz, $status) = Compress::Raw::Lzma::AloneEncoder->new(
    Filter => $filter,
);
die "Cannot create encoder: $status\n" unless $lz;

Using preset-based LZMA2 filter

use strict;
use warnings;

use Compress::Raw::Lzma;

# Use preset instead of manually configuring parameters
# Preset 9 = maximum compression
my $filter = Lzma::Filter::Lzma2::Preset(9 | LZMA_PRESET_EXTREME);

my ($lz, $status) = Compress::Raw::Lzma::StreamEncoder->new(
    Filter => $filter,
);
die "Cannot create encoder: $status\n" unless $lz;

Combining Delta filter with LZMA2

use strict;
use warnings;

use Compress::Raw::Lzma;

# Delta filter is useful for data with small changes between bytes
# (e.g., uncompressed images, audio samples)
my @filters = (
    Lzma::Filter::Delta(
        Type => LZMA_DELTA_TYPE_BYTE,
        Distance => 1,
    ),
    Lzma::Filter::Lzma2(
        DictSize => 8 * 1024 * 1024,
    ),
);

my ($lz, $status) = Compress::Raw::Lzma::StreamEncoder->new(
    Filter => \@filters,
    Check => LZMA_CHECK_CRC32,
);
die "Cannot create encoder: $status\n" unless $lz;

# Compress image or audio data
my $raw_data = ...;
my $compressed = '';

$lz->code($raw_data, $compressed);
$lz->flush($compressed);

Using BCJ filter for x86 executable compression

use strict;
use warnings;

use Compress::Raw::Lzma;

# BCJ (Branch/Call/Jump) filter optimizes compression of x86 binaries
my @filters = (
    Lzma::Filter::X86(Offset => 0),
    Lzma::Filter::Lzma2(),
);

my ($lz, $status) = Compress::Raw::Lzma::StreamEncoder->new(
    Filter => \@filters,
    Check => LZMA_CHECK_SHA256,
);
die "Cannot create encoder: $status\n" unless $lz;

# Read and compress x86 binary
open my $fh, '<', 'program.exe' or die $!;
binmode $fh;
my $binary = do { local $/; <$fh> };
close $fh;

my $compressed = '';
$lz->code($binary, $compressed);
$lz->flush($compressed);

print "Original: ", length($binary), " bytes\n";
print "Compressed: ", length($compressed), " bytes\n";

Using ARM filter for ARM binaries

use strict;
use warnings;

use Compress::Raw::Lzma;

# For ARM executables
my @filters = (
    Lzma::Filter::ARM(),
    Lzma::Filter::Lzma2(
        DictSize => 4 * 1024 * 1024,
    ),
);

my ($lz, $status) = Compress::Raw::Lzma::StreamEncoder->new(
    Filter => \@filters,
);
die "Cannot create encoder: $status\n" unless $lz;

Maximum compression with multiple filters

use strict;
use warnings;

use Compress::Raw::Lzma;

# Combine filters for maximum compression
my @filters = (
    Lzma::Filter::Delta(Distance => 1),
    Lzma::Filter::Lzma2(
        DictSize => 64 * 1024 * 1024,  # 64 MB
        Lc => 4,
        Lp => 0,
        Pb => 2,
        Mode => LZMA_MODE_NORMAL,
        Nice => 273,
        Mf => LZMA_MF_BT4,
        Depth => 1024,
    ),
);

my ($lz, $status) = Compress::Raw::Lzma::StreamEncoder->new(
    Filter => \@filters,
    Check => LZMA_CHECK_SHA256,
);
die "Cannot create encoder: $status\n" unless $lz;

Misc

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

Returns the version of the underlying lzma library this module is using at run-time as a number.

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

Returns the version of the underlying lzma library this module is using at run-time as a string.

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

Returns the version of the underlying lzma library this module was using at compile-time as a number.

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

Returns the version of the underlying lzma library this module was using at compile-time as a string.

Constants

The following lzma constants are exported by this module.

Return/Status Codes

LZMA_OK: Operation completed successfully.
LZMA_STREAM_END: End of stream was reached. The complete compressed data has been decoded/encoded.
LZMA_NO_CHECK: Input stream has no integrity check.
LZMA_UNSUPPORTED_CHECK: Cannot calculate the integrity check (not supported by this build).
LZMA_GET_CHECK: Integrity check type is now available.
LZMA_MEM_ERROR: Cannot allocate memory.
LZMA_MEMLIMIT_ERROR: Memory usage limit was reached.
LZMA_FORMAT_ERROR: File format not recognized.
LZMA_OPTIONS_ERROR: Invalid or unsupported options.
LZMA_DATA_ERROR: Data is corrupt.
LZMA_BUF_ERROR: No progress is possible (stream is truncated or corrupt).
LZMA_PROG_ERROR: Programming error (should never happen in correct usage).

Flush Modes

LZMA_RUN: Continue coding. Used for normal operation.
LZMA_SYNC_FLUSH: Make all the input available at output. Not commonly used with LZMA.
LZMA_FULL_FLUSH: Finish encoding of the current Block. Not commonly used.
LZMA_FINISH: Finish the coding operation. All input must have been given to the encoder.

Integrity Check Types

LZMA_CHECK_NONE: No Check is calculated.
LZMA_CHECK_CRC32: CRC32 using the polynomial from IEEE-802.3.
LZMA_CHECK_CRC64: CRC64 using the polynomial from ECMA-182.
LZMA_CHECK_SHA256: SHA-256 checksum.
LZMA_CHECK_ID_MAX: Maximum valid Check ID.
LZMA_CHECK_SIZE_MAX: Maximum size of any Check algorithm.

Preset and Compression Level

LZMA_PRESET_DEFAULT: Default compression preset (currently 6).
LZMA_PRESET_LEVEL_MASK: Mask for preset level (0-9).
LZMA_PRESET_EXTREME: Extreme compression preset flag. Can be combined with preset level using bitwise OR (e.g., 6 | LZMA_PRESET_EXTREME).

Stream Flags

LZMA_TELL_NO_CHECK: Accept streams with no integrity check.
LZMA_TELL_UNSUPPORTED_CHECK: Accept streams with unsupported integrity check.
LZMA_TELL_ANY_CHECK: Accept any type of integrity check.
LZMA_CONCATENATED: Enable support for concatenated streams.

Match Finder Types

LZMA_MF_HC3: Hash Chain with 3 byte hashing.
LZMA_MF_HC4: Hash Chain with 4 byte hashing.
LZMA_MF_BT2: Binary Tree with 2 byte hashing.
LZMA_MF_BT3: Binary Tree with 3 byte hashing.
LZMA_MF_BT4: Binary Tree with 4 byte hashing (default and recommended).

Compression Mode

LZMA_MODE_FAST: Fast compression mode.
LZMA_MODE_NORMAL: Normal compression mode (default).

Dictionary and Parameter Limits

LZMA_DICT_SIZE_MIN: Minimum dictionary size (4 KiB).
LZMA_DICT_SIZE_DEFAULT: Default dictionary size.
LZMA_LCLP_MIN: Minimum for lc and lp (0).
LZMA_LCLP_MAX: Maximum for lc and lp (4).
LZMA_LC_DEFAULT: Default number of literal context bits (3).
LZMA_LP_DEFAULT: Default number of literal position bits (0).
LZMA_PB_MIN: Minimum number of position bits (0).
LZMA_PB_MAX: Maximum number of position bits (4).
LZMA_PB_DEFAULT: Default number of position bits (2).

BCJ (Branch/Call/Jump) Filters

Architecture-specific filters for executable code:

LZMA_FILTER_X86: Filter for x86 (32-bit and 64-bit) binaries.
LZMA_FILTER_POWERPC: Filter for Big endian PowerPC binaries.
LZMA_FILTER_IA64: Filter for IA-64 (Itanium) binaries.
LZMA_FILTER_ARM: Filter for ARM binaries.
LZMA_FILTER_ARMTHUMB: Filter for ARM-Thumb binaries.
LZMA_FILTER_SPARC: Filter for SPARC binaries.

Delta Filter

LZMA_FILTER_DELTA: Delta filter ID.
LZMA_DELTA_TYPE_BYTE: Byte-wise delta calculation.
LZMA_DELTA_DIST_MIN: Minimum delta distance (1).
LZMA_DELTA_DIST_MAX: Maximum delta distance (256).

LZMA Filters

LZMA_FILTER_LZMA2: LZMA2 filter (used in .xz format).
LZMA_FILTERS_MAX: Maximum number of filters in a chain (4).

Stream Header and Block

LZMA_STREAM_HEADER_SIZE: Size of Stream Header (12 bytes).
LZMA_BLOCK_HEADER_SIZE_MIN: Minimum size of Block Header.
LZMA_BLOCK_HEADER_SIZE_MAX: Maximum size of Block Header.
LZMA_BACKWARD_SIZE_MIN: Minimum Backward Size.

Version Information

LZMA_VERSION: Encoded version number of liblzma.
LZMA_VERSION_MAJOR: Major version number.
LZMA_VERSION_MINOR: Minor version number.
LZMA_VERSION_PATCH: Patch version number.
LZMA_VERSION_STABILITY: Stability indicator.
LZMA_VERSION_STABILITY_STRING: Stability as string (e.g., "alpha", "beta", "stable").
LZMA_VERSION_STRING: Full version string.

SUPPORT

General feedback/questions/bug reports should be sent to https://github.com/pmqs/Compress-Raw-Lzma/issues (preferred) or https://rt.cpan.org/Public/Dist/Display.html?Name=Compress-Raw-Lzma.

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);

Compression examples

Simple compression with EasyEncoder

Streaming compression with AppendOutput

Using custom filters with StreamEncoder

Using multiple filters (BCJ + LZMA2)

Uncompression

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

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

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

Uncompression examples

Simple uncompression with AutoDecoder

Streaming uncompression with LimitOutput

Uncompressing specific format with AloneDecoder

Filters

Lzma::Filter::Lzma

Lzma::Filter::BCJ

Lzma::Filter::Delta

Filter examples

Using LZMA2 filter with custom dictionary size

Using LZMA1 filter for legacy .lzma format

Using preset-based LZMA2 filter

Combining Delta filter with LZMA2

Using BCJ filter for x86 executable compression

Using ARM filter for ARM binaries

Maximum compression with multiple filters

Misc

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

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

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

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

Constants

Return/Status Codes

Flush Modes

Integrity Check Types

Preset and Compression Level

Stream Flags

Match Finder Types

Compression Mode

Dictionary and Parameter Limits

BCJ (Branch/Call/Jump) Filters

Delta Filter

LZMA Filters

Stream Header and Block

Version Information

SUPPORT

SEE ALSO

AUTHOR

MODIFICATION HISTORY

COPYRIGHT AND LICENSE

Module Install Instructions