


=encoding UTF-8

=head1 NAME

Gzip::Libdeflate - Libdeflate compression library

=head1 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 L<F<synopsis.pl>|https://fastapi.metacpan.org/source/BKB/Gzip-Libdeflate-0.11_01/examples/synopsis.pl> in the distribution.)


=head1 VERSION

This documents version 0.11_01 of Gzip-Libdeflate
corresponding to L<git commit 484cc45fe40e77dc8fb50960f9c67257b07a3f30|https://github.com/benkasminbullock/gzip-libdeflate/commit/484cc45fe40e77dc8fb50960f9c67257b07a3f30> released on Sun Nov 2 22:11:41 2025 +0900. This
distribution also includes libdeflate version 1.25. 

=head1 DESCRIPTION

This module provides an interface to libdeflate. Libdeflate is a
newly-written compression library which offers the same C<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.

=head1 INSTALLATION

An ISO C99 compiler is required. For example Gcc (Gnu Compiler
Collection) version 4.9 or later, or Clang version 3.9 or later, are
required. This restriction is imposed by libdeflate.

=head1 METHODS

=head2 compress

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

Compress input C<$thing> using whatever compression level and type you
have specified for C<$gl> in L</new>.

=head2 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 L</File::Slurper> to read and
write the binary files. 

For the opposite operation, see L</decompress_file>.

This method was added in version 0.03 of the module.

=head2 decompress

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

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

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

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

=head2 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 C<zlib> or C<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 L</File::Slurper> to read and
write the binary files.

For the opposite operation, see L</compress_file>.

This method was added in version 0.03 of the module.

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

=head2 get_type

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

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

This method was added in version 0.03 of the module.

=head2 new

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

Possible options are

=over

=item 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 L</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.

=item type

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

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

=back

=head1 ERROR HANDLING

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

=head1 DEPENDENCIES

=over

=item L<File::Slurper>

File::Slurper is used by L</compress_file> and L</decompress_file> to
read and write binary data.

=back

=head1 SEE ALSO

=head2 About libdeflate

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

=over

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

=back

See the L<Libdeflate github
repository|https://github.com/ebiggers/libdeflate> for full
information.

=head2 CPAN modules

=over

=item L<Alien::libdeflate>

=back



=head1 AUTHOR

Ben Bullock, <benkasminbullock@gmail.com>

=head1 COPYRIGHT & LICENCE

This package and associated files are copyright (C) 
2021-2025
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
Copyright 2024 Google LLC

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.


