
NAME
Compress::Zlib - Compression, streams, and handle wrappers for zlib
DESCRIPTION
Compress and uncompress data using the native zlib library.
Requires Compress::Zlib::Raw 1.1.0 or newer, which bundles zlib 1.4. Native libraries are loaded from that distribution's resources.
SYNOPSIS
use Compress::Zlib;
my $compressed = compress('Hello, world!'.encode('utf8'));
my $original = uncompress($compressed).decode('utf8');
say $original; # Hello, world!
# Write and read a gzip file.
gzspurt('message.gz', 'Hello, world!');
say gzslurp('message.gz'); # Hello, world!
STREAMING
Stream objects compress or decompress chunks. Each object handles one stream in one direction. The default format is zlib; use :gzip for gzip or :deflate for raw deflate.
use Compress::Zlib;
my $compressor = Compress::Zlib::Stream.new(:gzip);
my $compressed = Buf.new;
for 'Hello, ', 'world!' -> $chunk {
$compressed.append($compressor.deflate($chunk.encode('utf8')));
}
$compressed.append($compressor.finish);
my $decompressor = Compress::Zlib::Stream.new(:gzip);
say $decompressor.inflate($compressed).decode('utf8'); # Hello, world!
say $decompressor.finished; # True
HANDLE WRAPPER
zwrap($handle, :$gzip, :$zlib, :$deflate --> Compress::Zlib::Wrap)
Returns a wrapped handle that reads and writes compressed data. The handle can be a filehandle or socket. Compress::Zlib::Wrap.new($handle) also constructs a wrapper.
Use send to write data and get to read a line. For example, given a connected $handle:
my $wrapped = zwrap($handle);
$wrapped.send('data');
my $response = $wrapped.get;
Read a gzip file as lines:
use Compress::Zlib;
my $file = 'data.txt.gz';
my $handle = open $file;
my $wrapped = zwrap($handle, :gzip);
for $wrapped.lines {
.print;
}
$wrapped.close;
SLURP AND SPURT
gzslurp($filename, :$bin)
Reads a gzip file. Pass :bin to return binary data instead of text.
gzspurt($filename, $stuff, :$bin)
Writes a gzip file. Supply a Blob for binary data.
STREAM CLASS
new(:$gzip, :$zlib, :$deflate --> Compress::Zlib::Stream)
Creates an object for compression or decompression, but not both. Defaults to zlib format. :gzip selects gzip; :deflate selects raw deflate. Stream compression uses level 6.
finished(--> Bool)
Returns true when the stream is finished. No further input can be supplied.
bytes-left(--> Int)
After decompression reaches the stream end, returns the number of unused bytes in the last input buffer. Use this to locate data following the stream.
inflate(Buf $data --> Buf)
Decompresses a chunk of data.
deflate(Buf $data --> Buf)
Compresses a chunk of data.
flush(--> Buf)
Returns an empty buffer for an initialized stream. inflate and deflate already use Z_SYNC_FLUSH. Call this when your protocol requires a flush, such as after sending a complete request.
finish(--> Buf)
Flushes remaining compression output and releases native stream resources. Append the returned data when compressing. Call this when compression is complete or when you are finished with the object.
BUFFER FUNCTIONS
These functions handle zlib format data, not gzip or raw deflate.
compress(Blob $data, Int $level = 6 --> Buf)
Compresses binary data. Levels range from -1 through 9; -1 selects zlib's default level, 0 disables compression, and 9 selects maximum compression. The default is 6. Compressing an empty buffer is valid.
uncompress(Blob $data --> Buf)
Uncompresses previously compressed data. Empty, malformed, or truncated compressed input throws an exception.
AUTHORS AND MAINTAINERS
Originally written by Andrew Egeler (retupmoca). Maintained in this fork by Matt Doughty.
LICENSE AND COPYRIGHT
The Raku wrapper uses the MIT License. The native libraries are supplied by Compress::Zlib::Raw under the zlib license.