IO::UNCOMPRESS::ANYUNCOMPRESS(3pm)

📦
version 5.42.3 · 17 versions
, in alpine 3.24

💅 IO::Uncompress::AnyUncompress(3pm) — Perl Programmers Reference Guide

okay so bestie, listen — this is the manual page for IO::Uncompress::AnyUncompress, straight out of the Perl Programmers Reference Guide, and it's about to be your new fave 🫶

✨ NAME ✨

IO::Uncompress::AnyUncompress — the icon herself. She uncompresses gzip, zip, bzip2, zstd, xz, lzma, lzip, lzf or lzop files and buffers. yes, all of them. a whole squad. 💅

🌸 SYNOPSIS 🌸

use IO::Uncompress::AnyUncompress qw(anyuncompress $AnyUncompressError) ;

my $status = anyuncompress $input => $output [,OPTS]
    or die "anyuncompress failed: $AnyUncompressError\n";

my $z = IO::Uncompress::AnyUncompress->new( $input [OPTS] )
    or die "anyuncompress failed: $AnyUncompressError\n";

$status = $z->read($buffer)
$status = $z->read($buffer, $length)
$status = $z->read($buffer, $length, $offset)
$line = $z->getline()
$char = $z->getc()
$char = $z->ungetc()
$char = $z->opened()

$data = $z->trailingData()
$status = $z->nextStream()
$data = $z->getHeaderInfo()
$z->tell()
$z->seek($position, $whence)
$z->binmode()
$z->fileno()
$z->eof()
$z->close()

$AnyUncompressError ;

# IO::File mode

<$z>
read($z, $buffer);
read($z, $buffer, $length);
read($z, $buffer, $length, $offset);
tell($z)
seek($z, $position, $whence)
binmode($z)
fileno($z)
eof($z)
close($z)

like, look at all those methods. she's versatile. she contains multitudes. ✨

🦋 DESCRIPTION 🦋

So here's the tea ☕ — this module gives you a Perl interface that lets you read files and buffers that were compressed with a whole bunch of different compression libraries. not just one. a variety. she's flexible like that 💁‍♀️

The formats she supports are, in order:

and the best part? the module will auto-detect which one of these supported compression formats is being used — if any. 👑

like she just knows. no cap. you don't have to tell her, she figures it out. main character energy fr fr 💜

that's part 1 down, more coming — don't go anywhere 🎀

✨ Functional Interface ✨

Okay so there's a top-level function called anyuncompress that just does the whole thing in one go — "one-shot" uncompression, buffer-to-buffer, file-to-file, whatever combo you need 💅. If you want to be all up in the details and micro-manage the process, go peek at the "OO Interface" section instead.

use IO::Uncompress::AnyUncompress qw(anyuncompress $AnyUncompressError) ;

anyuncompress $input_filename_or_reference => $output_filename_or_reference [,OPTS]
    or die "anyuncompress failed: $AnyUncompressError\n";

Heads up bestie: the functional interface needs Perl5.005 or better. No ancient Perl energy here 🫶.

🎀 anyuncompress $input_filename_or_reference => $output_filename_or_reference [, OPTS] 🎀

anyuncompress wants at least two params — $input_filename_or_reference and $output_filename_or_reference — plus zero or more optional ones (those live down in "Optional Parameters", iykyk).

💖 The $input_filename_or_reference parameter

This one tells the function where your compressed data is coming from. It's giving flexible, honestly. It can be any of these:

  • A filename — if $input_filename_or_reference is a plain old simple scalar, it gets treated as a filename. That file gets opened for reading and the input data is read straight out of it.
  • A filehandle — if $input_filename_or_reference is a filehandle, the input data is read from it. And plot twist: the string '-' works as an alias for standard input 👑
  • A scalar reference — if $input_filename_or_reference is a scalar reference, the input data gets read from $$input_filename_or_reference.
  • An array reference — if $input_filename_or_reference is an array reference, every element in the array has to be a filename. The input data is read from each file in turn. And the whole array gets walked first to make sure it only contains valid filenames before any data gets uncompressed (responsible queen behavior fr).
  • An Input FileGlob string — if $input_filename_or_reference is a string wrapped in the characters < and >, anyuncompress assumes it's an input fileglob string. The input is then the list of files that match the fileglob. Peep File::GlobMapper for the deets.
If $input_filename_or_reference is literally any other type, undef gets returned. That's it. That's the vibe check 💀

💖 The $output_filename_or_reference parameter

This one controls where the uncompressed data ends up. Also very flexible:

  • A filename — if $output_filename_or_reference is a simple scalar, it's assumed to be a filename. It gets opened for writing and the uncompressed data is written into it.
  • A filehandle — if $output_filename_or_reference is a filehandle, the uncompressed data is written to it. And '-' works as an alias for standard output 🌈
  • A scalar reference — if $output_filename_or_reference is a scalar reference, the uncompressed data gets stored in $$output_filename_or_reference.
  • An Array Reference — if $output_filename_or_reference is an array reference, the uncompressed data gets pushed onto the array. Slay.
  • An Output FileGlob — if $output_filename_or_reference is a string wrapped in the characters < and >, anyuncompress assumes it's an output fileglob string. The output is then the list of files that match the fileglob.
⚠️ When $output_filename_or_reference is a fileglob string, $input_filename_or_reference also has to be a fileglob string. Anything else is an error. Periodt.

Check File::GlobMapper for more.

And yeah, if $output_filename_or_reference is any other type, undef comes back at you.

🌸 Notes

Okay important note: when $input_filename_or_reference maps to multiple compressed files/buffers and $output_filename_or_reference is a single file/buffer, then after uncompression $output_filename_or_reference will contain a concatenation of all the uncompressed data from each of the input files/buffers. All of it. Together. One big blob 🫶

🌈 Optional Parameters 🌈

The optional params for the one-shot anyuncompress are (for the most part) identical to the ones used with the OO interface over in the "Constructor Options" section. The exceptions are listed right here:

  • AutoClose => 0|1 — this one applies to any input or output data streams you hand to anyuncompress that are filehandles. If AutoClose is specified and the value is true, it'll result in all input and/or output filehandles being closed once anyuncompress has completed. Defaults to 0.
  • BinModeOut => 0|1 — this option is now a no-op. All files will be written in binmode. That's it, that's the whole thing 💀
  • Append => 0|1 — the behaviour here depends on the type of output data stream:
    • A Buffer — if Append is enabled, all uncompressed data will be appended to the end of the output buffer. Otherwise the output buffer gets cleared before any uncompressed data is written to it.
    • A Filename — if Append is enabled, the file is opened in append mode. Otherwise the contents of the file, if any, get truncated before any uncompressed data is written to it.
    • A Filehandle — if Append is enabled, the filehandle gets positioned to the end of the file via a call to seek before any uncompressed data is written to it. Otherwise the file pointer doesn't move.

So when Append is specified and set to true, it'll append all uncompressed data to the output data stream. Which means: output is a filehandle → it does a seek to the eof before writing any uncompressed data. Output is a filename → it gets opened for appending. Output is a buffer → all uncompressed data gets appended to the existing buffer.

Conversely, when Append isn't specified, or it's present and set to false, it operates like this: output is a filename → it truncates the contents of the file before writing any uncompressed data. Output is a filehandle → its position is not changed. Output is a buffer → it gets wiped before any uncompressed data is output.

Defaults to 0.

  • MultiStream => 0|1 — if the input file/buffer contains multiple compressed data streams, this option will uncompress the whole lot as a single data stream. Defaults to 0.
  • TrailingData => $scalar — returns the data, if any, that's hanging out immediately after the compressed data stream once uncompression is complete 🦋. This is your girl when there's useful info immediately following the compressed data stream and you don't know the length of the compressed data stream.
    • If the input is a buffer, trailingData returns everything from the end of the compressed data stream to the end of the buffer.
    • If the input is a filehandle, trailingData returns the data that's left in the filehandle input buffer once the end of the compressed data stream has been reached. Then you can use the filehandle to read the rest of the input file 👑
Lowkey don't even bother using trailingData if the input is a filename. Just don't.

And if you already know the length of the compressed data stream before you start uncompressing, you can dodge trailingData entirely by setting the InputLength option 💅

⭐ OneShot Examples ⭐

Wanna read the contents of the file file1.txt.Compressed and write the uncompressed data out to the file file1.txt? Say less:

use strict ;
use warnings ;
use IO::Uncompress::AnyUncompress qw(anyuncompress $AnyUncompressError) ;

my $input = "file1.txt.Compressed";
my $output = "file1.txt";
anyuncompress $input => $output
    or die "anyuncompress failed: $AnyUncompressError\n";

Reading from an existing Perl filehandle, $input, and writing the uncompressed data to a buffer, $buffer? Iconic:

use strict ;
use warnings ;
use IO::Uncompress::AnyUncompress qw(anyuncompress $AnyUncompressError) ;
use IO::File ;

my $input = IO::File->new( "<file1.txt.Compressed" )
    or die "Cannot open 'file1.txt.Compressed': $!\n" ;
my $buffer ;
anyuncompress $input => \$buffer
    or die "anyuncompress failed: $AnyUncompressError\n";

Wanna uncompress all the files in the directory /my/home that match *.txt.Compressed and store the compressed data in that same directory? Bestie, easy:

use strict ;
use warnings ;
use IO::Uncompress::AnyUncompress qw(anyuncompress $AnyUncompressError) ;

anyuncompress '</my/home/*.txt.Compressed>' => '</my/home/#1.txt>'
    or die "anyuncompress failed: $AnyUncompressError\n";

And if you wanna compress each file one at a time instead, this'll do the trick:

use strict ;
use warnings ;
use IO::Uncompress::AnyUncompress qw(anyuncompress $AnyUncompressError) ;

for my $input ( glob "/my/home/*.txt.Compressed" )
{
    my $output = $input;
    $output =~ s/.Compressed// ;
    anyuncompress $input => $output
        or die "Error compressing '$input': $AnyUncompressError\n";
}

🎀 OO Interface 🎀

✨ Constructor ✨

okay so here's the vibe check on how you build one of these bad boys. the constructor for IO::Uncompress::AnyUncompress looks literally like this:

my $z = IO::Uncompress::AnyUncompress->new( $input [OPTS] )
    or die "IO::Uncompress::AnyUncompress failed: $AnyUncompressError\n";

it takes exactly one mandatory parameter, $input (we'll get to that in a sec, don't worry), plus zero or more OPTS, which are all explained down in "Constructor Options". 🫶

it hands you back an IO::Uncompress::AnyUncompress object if everything slays, and undef if it doesn't 😭. when it fails, $AnyUncompressError is gonna hold the error message for you. no cap.

if you're running Perl 5.005 or better, the object $z that comes back can be used exactly like an IO::File filehandle — like, the whole point. that means every normal input file operation works on $z. for example, to read a line from a compressed file/buffer you can do either of these:

$line = $z->getline();
$line = <$z>;

here's a lil baby example of using the OO interface to read the compressed file myfile.Compressed and write its contents out to stdout. iconic behaviour honestly:

my $filename = "myfile.Compressed";
my $z = IO::Uncompress::AnyUncompress->new($filename)
    or die "IO::Uncompress::AnyUncompress failed: $AnyUncompressError\n";

while (<$z>) {
    print $_;
}
$z->close();

peep "EXAMPLES" for even more, bestie 💖

so the mandatory parameter $input is what tells the module where the compressed data is coming from. it can take one of three forms:

🌸 A filename

if $input is a scalar, it's treated as a filename. the file gets opened for reading and the compressed data gets read from it. simple as that.

🌸 A filehandle

if $input is a filehandle, the compressed data gets read from it. the string '-' works as an alias for standard input, super handy.

🌸 A scalar reference

if $input is a scalar reference, the compressed data gets read from $$input. yes, double-dollar. it's giving dereference realness 💅

🦋 Constructor Options 🦋

first thing: option names are case insensitive and can optionally be prefixed by a -. so all of these are 100% valid, pick your fighter:

-AutoClose
-autoclose
AUTOCLOSE
autoclose

OPTS is any combo of the following options, enjoy 💜

  • AutoClose => 0|1 — this one's only valid when $input is a filehandle. if you specify it and the value is true, the file gets closed once either the close method is called or the IO::Uncompress::AnyUncompress object is destroyed. defaults to 0.
  • MultiStream => 0|1 — lets multiple concatenated compressed streams be treated as one single compressed stream. decompression stops once either the end of the file/buffer is reached, an error happens (premature eof, corrupt compressed data), or the end of a stream isn't immediately followed by the start of another stream. defaults to 0.
  • Prime => $string — this bad boy uncompresses the contents of $string before it processes the input file/buffer. lowkey a lifesaver when the compressed data is embedded inside another file/data structure and there's just no way to work out where the compressed data begins without reading the first few bytes first. in that situation, you can prime the uncompression with those bytes using this option. 🧚
  • Transparent => 0|1 — if this is set and the input file/buffer is not compressed data, the module will let you read it anyway. also, if the input file/buffer does contain compressed data and there's non-compressed data right after it, setting this option makes the module treat the whole file/buffer as a single data stream. defaults to 1.
  • BlockSize => $num — when reading the compressed input data, IO::Uncompress::AnyUncompress reads it in blocks of $num bytes. defaults to 4096.
  • InputLength => $size — when present, this limits the number of compressed bytes read from the input file/buffer to $size. so useful when there's actual useful data sitting directly after the compressed data stream and you already know beforehand the exact length of that compressed stream. mostly used when reading from a filehandle — in that case the file pointer gets left pointing at the first byte directly after the compressed data stream. defaults to off.
  • Append => 0|1 — controls what the read method does with uncompressed data. if set to 1, all uncompressed data gets appended to the output parameter of the read method. if set to 0, the contents of the output parameter of the read method get overwritten by the uncompressed data. defaults to 0.
  • Strict => 0|1 — controls whether those extra checks down below get used while decompressing. when Strict is on, the extra tests happen; when it's off, they don't. default for this one is off.
  • RawInflate => 0|1 — when auto-detecting the compressed format, try testing for raw-deflate (RFC 1951) content using the IO::Uncompress::RawInflate module. why isn't this the default? because RFC 1951 content can only be detected by attempting to uncompress it — that process is error prone and can result in false positives. defaults to 0.
  • UnLzma => 0|1 — when auto-detecting the compressed format, try testing for lzma_alone content using the IO::Uncompress::UnLzma module. same deal as above: it's not default because lzma_alone content can only be detected by actually attempting to uncompress it, which is error prone and can result in false positives. defaults to 0.
heads up bestie: those last two are off by default for a reason — detection-by-trying is genuinely error prone and can give you false positives, so don't just flip them on and forget it 🙈

💅 METHODS 💅

okay bestie this is where it gets good — every method the object can do, one by one, no skips 🫶

🌸 read 🌸

Usage is

$status = $z->read($buffer)

Reads a block of compressed data (the size of the compressed block is determined by the Buffer option in the constructor), uncompresses it and writes any uncompressed data into $buffer. If the Append parameter is set in the constructor, the uncompressed data will be appended to the $buffer parameter. Otherwise $buffer will be overwritten.

Returns the number of uncompressed bytes written to $buffer, zero if eof or a negative number on error.

🌸 read (the sequel, yes there's two of them) 🌸

Usage is

$status = $z->read($buffer, $length)
$status = $z->read($buffer, $length, $offset)

$status = read($z, $buffer, $length)
$status = read($z, $buffer, $length, $offset)

Attempt to read $length bytes of uncompressed data into $buffer.

The main difference between this form of the read method and the previous one, is that this one will attempt to return exactly $length bytes. The only circumstances that this function will not is if end-of-file or an IO error is encountered.

Returns the number of uncompressed bytes written to $buffer, zero if eof or a negative number on error.

🎀 getline 🎀

Usage is

$line = $z->getline()
$line = <$z>

Reads a single line.

This method fully supports the use of the variable $/ (or $INPUT_RECORD_SEPARATOR or $RS when English is in use) to determine what constitutes an end of line. Paragraph mode, record mode and file slurp mode are all supported. iykyk ✨

🎀 getc 🎀

Usage is

$char = $z->getc()

Read a single character. one (1) little guy. iconic.

🎀 ungetc 🎀

Usage is

$char = $z->ungetc($string)

🦋 getHeaderInfo 🦋

Usage is

$hdr  = $z->getHeaderInfo();
@hdrs = $z->getHeaderInfo();

This method returns either a hash reference (in scalar context) or a list or hash references (in array context) that contains information about each of the header fields in the compressed data stream(s). 👑

🦋 tell 🦋

Usage is

$z->tell()
tell $z

Returns the uncompressed file offset.

🦋 eof 🦋

Usage is

$z->eof();
eof($z);

Returns true if the end of the compressed input stream has been reached. the end bestie, we made it 😭

💜 seek 💜

$z->seek($position, $whence);
seek($z, $position, $whence);

Provides a sub-set of the seek functionality, with the restriction that it is only legal to seek forward in the input file/buffer. It is a fatal error to attempt to seek backward. no going back, we only move forward here 💅

Note that the implementation of seek in this module does not provide true random access to a compressed file/buffer. It works by uncompressing data from the current offset in the file/buffer until it reaches the uncompressed offset specified in the parameters to seek. For very small files this may be acceptable behaviour. For large files it may cause an unacceptable delay.

The $whence parameter takes one the usual values, namely SEEK_SET, SEEK_CUR or SEEK_END.

Returns 1 on success, 0 on failure.

💜 binmode 💜

Usage is

$z->binmode
binmode $z ;

This is a noop provided for completeness. literally does nothing, but it's there for you 🫶

🌈 opened 🌈

$z->opened()

Returns true if the object currently refers to a opened file/buffer.

🌈 autoflush 🌈

my $prev = $z->autoflush()
my $prev = $z->autoflush(EXPR)

If the $z object is associated with a file or a filehandle, this method returns the current autoflush setting for the underlying filehandle. If EXPR is present, and is non-zero, it will enable flushing after every write/print operation.

If $z is associated with a buffer, this method has no effect and always returns undef.

⚠️ heads up bestie: the special variable $| cannot be used to set or retrieve the autoflush setting. not that one, nope 🙈

⭐ input_line_number ⭐

$z->input_line_number()
$z->input_line_number(EXPR)

Returns the current uncompressed line number. If EXPR is present it has the effect of setting the line number. Note that setting the line number does not change the current position within the file/buffer being read.

The contents of $/ are used to determine what constitutes a line terminator.

⭐ fileno ⭐

$z->fileno()
fileno($z)

If the $z object is associated with a file or a filehandle, fileno will return the underlying file descriptor. Once the close method is called fileno will return undef.

If the $z object is associated with a buffer, this method will return undef.

💖 close 💖

$z->close() ;
close $z ;

Closes the output file/buffer.

For most versions of Perl this method will be automatically invoked if the IO::Uncompress::AnyUncompress object is destroyed (either explicitly or by the variable with the reference to the object going out of scope). The exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In these cases, the close method will be called automatically, but not until global destruction of all live objects when the program is terminating.

Therefore, if you want your scripts to be able to run on all versions of Perl, you should call close explicitly and not rely on automatic closing. fr fr, just call it yourself 🙏

Returns true on success, otherwise 0.

If the AutoClose option has been enabled when the IO::Uncompress::AnyUncompress object was created, and the object is associated with a file, the underlying file will also be closed.

💖 nextStream 💖

Usage is

my $status = $z->nextStream();

Skips to the next compressed data stream in the input file/buffer. If a new compressed data stream is found, the eof marker will be cleared and $. will be reset to 0.

Returns 1 if a new stream was found, 0 if none was found, and -1 if an error was encountered.

🍓 trailingData 🍓

Usage is

my $data = $z->trailingData();

Returns the data, if any, that is present immediately after the compressed data stream once uncompression is complete. It only makes sense to call this method once the end of the compressed data stream has been encountered.

This option can be used when there is useful information immediately following the compressed data stream, and you don't know the length of the compressed data stream.

If the input is a buffer, trailingData will return everything from the end of the compressed data stream to the end of the buffer.

If the input is a filehandle, trailingData will return the data that is left in the filehandle input buffer once the end of the compressed data stream has been reached. You can then use the filehandle to read the rest of the input file.

Don't bother using trailingData if the input is a filename. like, genuinely, skip it 💀

If you know the length of the compressed data stream before you start uncompressing, you can avoid having to use trailingData by setting the InputLength option in the constructor.

🧚 IMPORTING 🧚

No symbolic constants are required by IO::Uncompress::AnyUncompress at present.

  • :all — Imports anyuncompress and $AnyUncompressError. Same as doing this
use IO::Uncompress::AnyUncompress qw(anyuncompress $AnyUncompressError) ;

✨ EXAMPLES ✨

okay so this heading is just. sitting here. all alone. the original page puts EXAMPLES in the section list and then there's literally nothing under it 🙈 not me leaving it exactly as I found it — it's giving mysterious, it's giving "the examples are left as an exercise", and no I will not be inventing any for you bestie, that's not my job 💅

🫶 SUPPORT 🫶

General feedback/questions/bug reports should be sent to <https://github.com/pmqs/IO-Compress/issues> (preferred) or <https://rt.cpan.org/Public/Dist/Display.html?Name=IO-Compress>.

👑 SEE ALSO 👑

Compress::Zlib, IO::Compress::Gzip, IO::Uncompress::Gunzip, IO::Compress::Deflate, IO::Uncompress::Inflate, IO::Compress::RawDeflate, IO::Uncompress::RawInflate, IO::Compress::Bzip2, IO::Uncompress::Bunzip2, IO::Compress::Lzma, IO::Uncompress::UnLzma, IO::Compress::Xz, IO::Uncompress::UnXz, IO::Compress::Lzip, IO::Uncompress::UnLzip, IO::Compress::Lzop, IO::Uncompress::UnLzop, IO::Compress::Lzf, IO::Uncompress::UnLzf, IO::Compress::Zstd, IO::Uncompress::UnZstd, IO::Uncompress::AnyInflate

IO::Compress::FAQ

File::GlobMapper, Archive::Zip, Archive::Tar, IO::Zlib

🌸 AUTHOR 🌸

This module was written by Paul Marquess, "pmqs@cpan.org". absolute legend, we stan 🫶

🦋 MODIFICATION HISTORY 🦋

See the Changes file.

Copyright (c) 2005-2026 Paul Marquess. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

and that's the whole page bestie, you read the entire thing, I'm so proud of you 😭💖✨

this was perl v5.42.3, dated 2026-11-03, and it's the IO::Unc...compress(3pm) page — go forth and uncompress responsibly 🎀

📦 where this page comes from