DPKG::COMPRESSION::FILEHANDLE(3perl)

✨ Dpkg::Compression::FileHandle(3perl) ✨

okay so bestie, welcome to the libdpkg-perl glow-up you didn't know you needed 💅 this little page is all about Dpkg::Compression::FileHandle — the class that handles compressed files for you, transparently, no cap 🫶

---

🎀 SYNOPSIS 🎀

like, here's the whole vibe in code form:

use Dpkg::Compression::FileHandle;

my ($fh, @lines);

$fh = Dpkg::Compression::FileHandle->new(filename => 'sample.gz');
print $fh "Something\n";
close $fh;

$fh = Dpkg::Compression::FileHandle->new();
open($fh, '>', 'sample.bz2');
print $fh "Something\n";
close $fh;

$fh = Dpkg::Compression::FileHandle->new();
$fh->open('sample.xz', 'w');
$fh->print("Something\n");
$fh->close();

$fh = Dpkg::Compression::FileHandle->new(filename => 'sample.gz');
@lines = <$fh>;
close $fh;

$fh = Dpkg::Compression::FileHandle->new();
open($fh, '<', 'sample.bz2');
@lines = <$fh>;
close $fh;

$fh = Dpkg::Compression::FileHandle->new();
$fh->open('sample.xz', 'r');
@lines = $fh->getlines();
$fh->close();

like, six whole ways to live your truth. pick your fighter ✨

---

💖 DESCRIPTION 💖

So Dpkg::Compression::FileHandle is a class that works exactly like any filehandle — but it deals with compressed files transparently. Like, you don't even have to think about it bestie, it just ✨works✨.

By default the compression scheme is guessed from the filename, but you can override that whole situation with the set_compression() method.

And if you don't open the file explicitly? It auto-opens on the first read or write operation — based on the filename set at creation time (or later with the set_filename() method). main character energy fr fr 👑

⚠️ Heads up: once a file has been opened, the filehandle must be closed before you can open another file. No multitasking, sorry babe 😭

---

🌈 STANDARD FUNCTIONS 🌈

The standard functions that act on filehandles should accept a Dpkg::Compression::FileHandle object transparently — including:

• open() (only when using the variant with 3 parameters, iykyk)
• close()
• binmode()
• eof()
• fileno()
• getc()
• print()
• printf()
• read()
• sysread()
• say()
• write()
• syswrite()
• seek()
• sysseek()
• tell()

💀 okay important caveat: seek() and sysseek() will only work on uncompressed files — because compressed files are really pipes to the compressor programs, and you literally can't seek on a pipe. sorry bestie, that's just physics 🫠

---

🦋 FileHandle METHODS 🦋

The class inherits from IO::File, so all methods that work on IO::File should work for Dpkg::Compression::FileHandle too. There may be exceptions though 👀

---

🌸 PUBLIC METHODS 🌸

$fh = Dpkg::Compression::FileHandle->new(%opts)

Creates a new filehandle that supports on-the-fly compression/decompression. obsessed ✨

Options:

• filename — see $fh->set_filename().
• compression — see $fh->set_compression().
• compression_level — see $fh->set_compression_level().
• add_comp_ext — if set to true, then the extension corresponding to the selected compression scheme is automatically added to the recorded filename. It is incompatible with automatic detection of the compression method. like, they cannot coexist bestie 🙈

$fh->ensure_open($mode, %opts)

Ensure the file is opened in the requested mode — "r" for read, "w" for write. The options are passed down to the compressor's spawn() call, if one is used. Opens the file with the recorded filename if needed. And if the file is already open but not in the requested mode? It errors out. dramatic but fair 💅

$fh->set_compression($comp)

Defines the compression method used. $comp should be one of the methods supported by Dpkg::Compression, or "none", or "auto".

• "none" → the file is uncompressed
• "auto" → the method must be guessed based on the filename extension used

$fh->set_compression_level($level)

Indicate the desired compression level. It should be a value accepted by the function compression_is_valid_level() of Dpkg::Compression. don't just make up numbers bestie 🎀

$fh->set_filename($name, [$add_comp_ext])

Use $name as the filename when the file must be opened/created. If $add_comp_ext is passed, it indicates whether the default extension of the compression method must be automatically added to the filename (or not).

$file = $fh->get_filename()

Returns the filename that would be used when the filehandle must be opened (both in read and write mode). This function errors out if "add_comp_ext" is enabled while the compression method is set to "auto". The returned filename includes the extension of the compression method if "add_comp_ext" is enabled. iconic behavior honestly ⭐

$ret = $fh->use_compression()

Returns "0" if no compression is used, and the compression method used otherwise. If the compression is set to "auto", the value returned depends on the extension of the filename obtained with the get_filename() method.

$real_fh = $fh->get_filehandle()

Returns the real underlying filehandle. Super useful if you want to pass it along in a derived class 🫶

---

🧚 DERIVED CLASSES 🧚

okay so if you want to create a class that inherits from Dpkg::Compression::FileHandle, you must be aware that the object is a reference to a GLOB that is returned by Symbol::gensym() — and as such, it's not a HASH. plot twist 😭

You can store internal data in a hash, but you have to use *$self->{...} to access the associated hash, like in the example below:

sub set_option {
    my ($self, $value) = @_;
    *$self->{option} = $value;
}

lowkey a vibe check moment but you got this 💜

---

🔥 CHANGES 🔥

Version 1.02 (dpkg 1.23.8)

• Change behavior: Change $fh->set_filename() to croak instead of warn on 'add_comp_ext' with a $filename with a compression extension. it got serious about it 💀

Version 1.01 (dpkg 1.17.11)

• New argument: $fh->ensure_open() accepts an %opts argument.

Version 1.00 (dpkg 1.15.6)

• Mark the module as public. slay 🎉

---

and that's the whole page bestie, no notes ✨ this was version 1.23.11-dirty, dated 2026-09-09, from the Dpkg::Compression::FileHandle(3perl) manual — go forth and compress responsibly 💅🎀🦋