/ 
File-Raw-Gzip-0.01
/ File::Raw::Gzip

NAME

File::Raw::Gzip - Gzip / zlib / raw deflate plugin for File::Raw

VERSION

Version 0.01

SYNOPSIS

Loading the module registers a single gzip plugin with File::Raw.

use File::Raw::Gzip;
use File::Raw qw(import);

# READ: decompress on the way in.
my $bytes = file_slurp("nginx.access.log.gz", plugin => 'gzip');

# WRITE: compress on the way out.
file_spew("out.gz", $payload, plugin => 'gzip', level => 9);

# zlib stream (RFC 1950) inside e.g. PNG files:
my $raw = file_slurp("inner.zlib", plugin => 'gzip', mode => 'zlib');

# Raw deflate (RFC 1951), no header:
my $raw = file_slurp("blob.deflate", plugin => 'gzip', mode => 'raw');

# STREAM: each_line over a gzip file without slurping it whole.
File::Raw::each_line("nginx.access.log.gz",
    sub { print "saw: $_\n" },
    plugin => 'gzip');

# CHAIN: read .csv.gz directly into AoA (with File::Raw::Separated).
my $rows = file_slurp("metrics.csv.gz",
                      plugin => ['gzip', 'csv']);

OPTIONS

Every plugin => 'gzip' dispatch accepts these trailing keys:

level

Compression level (0=none, 1=fastest, 9=smallest). Default 6. Encode-only; ignored on decode.

mode

One of gzip, zlib, raw, auto. Selects the wbits value handed to inflateInit2 / deflateInit2:

gzip - full gzip header + trailer (the .gz file format). Default for encode.
zlib - zlib stream (RFC 1950); the wrapper used inside e.g. PNG.
raw - raw deflate (RFC 1951); no header, used in zip archives.
auto - decode-only; zlib auto-detects gzip vs zlib headers. Default for decode.
chunk_size

Output buffer growth chunk in bytes. Default 131072 (128 KiB). Raise for very large inputs to reduce realloc churn; lower if memory is tight. Capped at 64 MiB.

strategy

Compression strategy. One of default, filtered, huffman_only, rle, fixed. Encode-only. Advanced; the default is correct for nearly all use cases.

mem_level

Memory level (1-9). Default 8. Encode-only. Advanced; trade memory for speed.

PLUGIN BEHAVIOUR

The READ phase pulls compressed bytes out of File::Raw's slurp buffer, inflates them through libz, and returns the decompressed bytes as one SV. The WRITE phase deflates the user payload before File::Raw writes it to disk.

The STREAM phase backs File::Raw::each_line($path, $cb, plugin => 'gzip'): File::Raw reads the compressed file in chunks, this plugin inflates each chunk and emits decompressed lines through $cb with $_ bound to the line (no trailing newline). The inflate state and the partial trailing line live in ctx->call_state across chunks, so memory is bounded regardless of the compressed file's size.

The RECORD phase isn't implemented: a gzip stream has no record boundaries to dispatch over.

Plugin chains

Because gzip is a pure byte transform, it composes cleanly through File::Raw's plugin chain. Put 'gzip' first in a READ and WRITE chains

# READ:  bytes -> inflate -> csv parse
my $rows = file_slurp("data.csv.gz",
                      plugin => ['gzip', 'csv']);

# WRITE: csv encode -> deflate -> bytes
file_spew("out.csv.gz", $rows,
          plugin => ['gzip', 'csv']);

each_line (the streaming path) is single-plugin only; chain composition belongs to the slurp/spew/append/atomic_spew calls.

INSTALLATION REQUIREMENTS

File::Raw::Gzip links against the system libz. The development package must be installed before perl Makefile.PL:

Debian / Ubuntu
apt-get install zlib1g-dev
RHEL / Fedora / CentOS
dnf install zlib-devel
macOS (Homebrew)
brew install zlib
FreeBSD
pkg install zlib-ng-compat
Strawberry Perl (Windows)

Already bundled; no extra install needed.

SEE ALSO

File::Raw - the underlying fast file IO layer.

IO::Compress::Gzip, IO::Uncompress::Gunzip - the in-memory and streaming codecs we link against in tests for wire-compatibility.

Compress::Raw::Zlib - the lower-level zlib binding;

AUTHOR

LNATION <email@lnation.org>

LICENSE AND COPYRIGHT

This software is Copyright (c) 2026 by LNATION <email@lnation.org>.

This is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)