The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

Gzip::Libdeflate - Libdeflate compression library

SYNOPSIS

    use Gzip::Libdeflate;
    my $gl = Gzip::Libdeflate->new (level => 12);
    my $out = $gl->compress ("ABCDEFG" x 2);
    print length ($out), "\n";
    my $rt = $gl->decompress ($out);
    print "$rt\n";
    

produces output

    29
    ABCDEFGABCDEFG

(This example is included as synopsis.pl in the distribution.)

VERSION

This documents version 0.07 of Gzip-Libdeflate corresponding to git commit 4596fb46fdec606730aac1a2d54e9fd977abe29b released on Mon Mar 25 21:32:18 2024 +0900. This distribution also includes libdeflate version 1.20.

DESCRIPTION

This module provides an interface to libdeflate. Libdeflate is a newly-written compression library which offers the same deflate form of compression as zlib, as used in gzip, libpng and many similar utilities. This distribution includes libdeflate within itself, so it is not necessary to have that on your system.

METHODS

compress

    my $comp_thing = $gl->compress ($thing);

Compress input $thing using whatever compression level and type you have specified for $gl in "new".

compress_file

    my $out = $gl->compress_file (%options);

File to compressed scalar:

    my $out = $gl->compress_file (in => $file);

File to compressed file:

    $gl->compress_file (in => $file, out => "$file.gz");

Scalar to compressed file:

    $gl->compress_file (from => $uncompressed, out => "$file.gz");

This is a convenience method which uses "File::Slurper" to read and write the binary files.

For the opposite operation, see "decompress_file".

This method was added in version 0.03 of the module.

decompress

    my $thing = $gl->decompress ($dthing);

Decompress $comp_thing into $thing. If you have chosen the zlib or deflate options in "new", you also need to specify the expected size of $thing.

    my $thing = $gl->decompress ($dthing, 1000);

In the gzip format, the size is stored within the data itself, so it doesn't need to be specified.

decompress_file

    my $out = $gl->decompress_file (%options);

Compressed file to scalar:

    my $out = $gl->decompress_file (in => $file);

Compressed file to file:

    $gl->decompress_file (in => "$file.gz", out => $file);

Compressed scalar to file:

    $gl->decompress_file (from => $compressed, out => $file);

If using zlib or deflate compression, a numerical size must also be specified.

    $gl->decompress_file (in => $zlib_file, out => $file, size => 9999);

This is a convenience method which uses "File::Slurper" to read and write the binary files.

For the opposite operation, see "compress_file".

This method was added in version 0.03 of the module.

get_level

    my $level = $gl->get_level ();

Retrieve the level of compression as a number.

This method was added in version 0.03 of the module.

get_type

    my $type = $gl->get_type ();

Retrieve the type of compression from an object as a string, either deflate, gzip (the default), or zlib.

This method was added in version 0.03 of the module.

new

    my $gl = Gzip::Libdeflate->new (%options);

Possible options are

level
    my $gl = Gzip::Libdeflate->new (level => 9);

A numerical argument of compression level from 1 (fast and poor compression) to 12 (slow and good compression). If you do not specify it, the default is 6. These correspond to the compression levels of zlib, but with extra compression levels 10-12 also added. See "About libdeflate" for details.

As with zlib, there is also a "zero compression" option of level 0 which just puts the input into the gzip format without compressing it at all.

type
    my $gl = Gzip::Libdeflate->new (type => 'deflate');

Change the type of compression. The default is type gzip but you can also choose deflate and zlib. These are all the same thing up to headers.

ERROR HANDLING

Errors are handled by warning and then returning an undefined value.

DEPENDENCIES

File::Slurper

File::Slurper is used by "compress_file" and "decompress_file" to read and write binary data.

SEE ALSO

About libdeflate

Libdeflate is a new library which offers the same form of deflate compression as offered by zlib. From its README:

    libdeflate is a library for fast, whole-buffer DEFLATE-based compression and decompression.

See the Libdeflate github repository for full information.

CPAN modules

Alien::libdeflate

AUTHOR

Ben Bullock, <bkb@cpan.org>

COPYRIGHT & LICENCE

This package and associated files are copyright (C) 2021-2024 Ben Bullock.

You can use, copy, modify and redistribute this package and associated files under the Perl Artistic Licence or the GNU General Public Licence.

Libdeflate's copyright and licence are as follows.

Copyright 2016 Eric Biggers

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.