IO::UNCOMPRESS::ANYUNCOMPRESS(3perl)

📦
version 5.44.0 · 14 versions
, in arch rolling

✨ NAME ✨

okay bestie, welcome to IO::Uncompress::AnyUncompress(3perl) from the Perl Programmers Reference Guide 💖. This is IO::Uncompress::AnyUncompress — she uncompresses gzip, zip, bzip2, zstd, xz, lzma, lzip, lzf or lzop file/buffer. No cap, she's the main character of compression detection. 💅

🦋 SYNOPSIS 🦋

here's the summoning circle, fr fr:

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)

🌸 DESCRIPTION 🌸

okay so this module hands you a Perl interface, and that interface lets you read files/buffers that were compressed by a whole variety of compression libraries. It's giving "one interface to read them all" energy, but make it Perl. 🫶

The formats she supports are lowkey a whole iconic lineup:

And the auto-detect? The module will auto-detect which, if any, of the supported compression formats is being used. She just knows, bestie. ✨

💖 Functional Interface 💖

Okay bestie, so there's a top-level function called anyuncompress that just does the whole thing in one shot — buffers, files, whatever, it handles it. If you want finer control over your uncompression journey though, you gotta go peek at the "OO Interface" section instead. That's the deluxe version. ✨

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 queen: this functional interface needs Perl5.005 or better. So if you're running some ancient vibe, this is not the function for you. 💀

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

So anyuncompress needs at least two parameters — $input_filename_or_reference and $output_filename_or_reference — plus however many optional ones your heart desires (check "Optional Parameters" for those).

🎀 The $input_filename_or_reference parameter 🎀

This parameter is literally the whole vibe check for where your compressed data is coming from. It can be so many things, it's giving main character energy:

  • A filename — If $input_filename_or_reference is a simple scalar, it's assumed to be a filename, periodt. The file gets opened for reading and the input data comes straight out of it. 🍓
  • A filehandle — If $input_filename_or_reference is a filehandle, the input data gets read from it. And listen — the string '-' works as an alias for standard input. Iconic. 💅
  • A scalar reference — If $input_filename_or_reference is a scalar reference, the input data is read from $$input_filename_or_reference.
  • An array reference — If $input_filename_or_reference is an array reference, every element in that array must be a filename. The input data gets read from each file in turn. And here's the tea: the complete array gets walked through first to make sure it only contains valid filenames before any data is even uncompressed. Safety first, bestie. 🛡️
  • An Input FileGlob string — If $input_filename_or_reference is a string wrapped in < and > characters, anyuncompress is like "oh that's a fileglob string" and treats the input as the list of files matching that fileglob. See File::GlobMapper for all the deets. 🌈
If $input_filename_or_reference is literally any other type? undef gets returned. That's it. That's the answer. Sorry bestie. 😭

💜 The $output_filename_or_reference parameter 💜

This one controls where the uncompressed data goes. And it's just as versatile, ngl:

  • A filename — If $output_filename_or_reference is a simple scalar, it's a filename, no cap. That file gets opened for writing and all the uncompressed data lands in it. ✨
  • A filehandle — If $output_filename_or_reference is a filehandle, the uncompressed data is written to it. And again, the string '-' is an alias for standard output. 🫶
  • A scalar reference — If $output_filename_or_reference is a scalar reference, the uncompressed data is 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. 🌸
  • An Output FileGlob — If $output_filename_or_reference is a string wrapped in < and > characters, anyuncompress assumes it's an output fileglob string, and the output is the list of files matching that fileglob.
⚠️ IMPORTANT: When $output_filename_or_reference is a fileglob string, $input_filename_or_reference must also be a fileglob string. Anything else? That's an error. Straight up. 🙈

See File::GlobMapper for more details.

And if $output_filename_or_reference is any other type? Yep — undef gets returned. Same energy as before. 💀

🦋 Notes 🦋

Okay so here's a cute little edge case you need to know about. When $input_filename_or_reference maps to multiple compressed files/buffers, and $output_filename_or_reference is just a single file/buffer — after uncompression, $output_filename_or_reference will contain a concatenation of all the uncompressed data from each of the input files/buffers. It just squishes them all together. The more you know. ⭐

🌟 Optional Parameters 🌟

So the optional parameters for the one-shot anyuncompress are — for the most part — identical to the ones used with the OO interface (head to the "Constructor Options" section for those). But there are exceptions, and here they are, listed below because of course:

  • "AutoClose => 0|1" — This one applies to any input or output data streams to anyuncompress that happen to be filehandles. If AutoClose is set and it's true, it'll result in all input and/or output filehandles getting closed once anyuncompress has completed its little job. This parameter defaults to 0. 🎀
  • "BinModeOut => 0|1" — Bestie, this option is now a no-op. All files get written in binmode anyway. It's giving retired legend. 💅
  • "Append => 0|1" — The behaviour here depends on what kind of output data stream you've got going on:
    • A Buffer — If Append is enabled, all uncompressed data gets 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 there are 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. Otherwise the file pointer stays exactly where it is, don't move, nope.

When Append is specified and set to true, it appends all uncompressed data to the output data stream. So — filehandle output means a seek to the eof before writing anything. Filename output means opened for appending. Buffer output means everything appended to the existing buffer. ✨

Conversely, when Append is not specified, or it's present and set to false, it operates like this: filename output truncates the file contents before writing anything; filehandle output leaves its position unchanged; buffer output gets wiped clean before any uncompressed data comes out. 🧹

Defaults to 0.

  • "MultiStream => 0|1" — If the input file/buffer contains multiple compressed data streams, this option uncompresses the whole lot as a single data stream. Obsessed. Defaults to 0. 🔥
  • "TrailingData => $scalar" — Returns the data (if any) that's sitting immediately after the compressed data stream once uncompression is done. This is your bestie when there's useful info right after the compressed stream and you have no clue how long the compressed data stream actually is. 🕵️
    • 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 whatever's left in the filehandle input buffer once the end of the compressed data stream has been reached. You can then use that filehandle to read the rest of the input file. 💜
    • 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 the whole trailingData situation by setting the InputLength option instead. Slay. 💅

🌈 OneShot Examples 🌈

💖 Example 1: file to file 💖

To read the contents of the file file1.txt.Compressed and write the uncompressed data to the file file1.txt:

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";

🦋 Example 2: filehandle to buffer 🦋

To read from an existing Perl filehandle, $input, and write the uncompressed data to a buffer, $buffer:

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";

✨ Example 3: the fileglob moment ✨

To uncompress all files in the directory "/my/home" that match "*.txt.Compressed" and store the compressed data in the same directory:

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";

👑 Example 4: one at a time, queen 👑

And if you want to compress each file one at a time, this will 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 🦋

okay bestie, now we're doing the OO interface, and it's lowkey the main character energy of this whole module. ✨

💖 Constructor 💖

The constructor for IO::Uncompress::AnyUncompress looks like this:

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

It takes one mandatory parameter, $input (we'll get to that in a sec), and zero or more OPTS, which are all about "Constructor Options" (spoiler: they're right below). 🫶

On success you get an IO::Uncompress::AnyUncompress object; on failure you get undef. And if it fails, $AnyUncompressError will hold the error message, so you can die with it like the code above. 💀

If you're running Perl 5.005 or better, the object $z can be used exactly like an IO::File filehandle. That means all the normal input file operations work on $z. For example, to read a line from a compressed file/buffer you can use either of these forms:

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

Here's a simple example of using the OO interface to read the compressed file myfile.Compressed and write its contents to stdout:

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

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

See "EXAMPLES" for further examples. 👑

The mandatory parameter $input is used to determine the source of the compressed data. It can take one of three forms:

  • A filename — if $input is a scalar, it's assumed to be a filename. That file gets opened for reading, and the compressed data is read from it.
  • A filehandle — if $input is a filehandle, the compressed data is read from it. The string '-' can be used as an alias for standard input.
  • A scalar reference — if $input is a scalar reference, the compressed data is read from $$input.

✨ Constructor Options ✨

The option names below are case insensitive and can optionally be prefixed by a '-'. So all of these are valid:

-AutoClose
-autoclose
AUTOCLOSE
autoclose

OPTS is a combination of the following options:

  • AutoClose => 0|1 — this one is only valid when the $input parameter is a filehandle. If you set it to true, the file will be 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 a single compressed stream. Decompression will stop once either the end of the file/buffer is reached, an error is encountered (premature eof, corrupt compressed data), or the end of a stream is not immediately followed by the start of another stream. Defaults to 0.
  • Prime => $string — this option will uncompress the contents of $string before processing the input file/buffer. It's useful when the compressed data is embedded in another file/data structure and it's not possible to work out where the compressed data begins without having to read the first few bytes. If that's the case, you can prime the uncompression with those bytes using this option. 🌸
  • Transparent => 0|1 — if this option is set and the input file/buffer is not compressed data, the module will allow reading of it anyway. In addition, if the input file/buffer does contain compressed data and there is non-compressed data immediately following it, setting this option will make this 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 will read it in blocks of $num bytes. Defaults to 4096.
  • InputLength => $size — when present, this option limits the number of compressed bytes read from the input file/buffer to $size. You'd use this when there's useful data directly after the compressed data stream and you know beforehand the exact length of the compressed data stream. It's mostly used when reading from a filehandle — in that case the file pointer will be left pointing to 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 will be appended to the output parameter of the read method. If set to 0, the contents of the output parameter of the read method will be overwritten by the uncompressed data. Defaults to 0.
  • Strict => 0|1 — controls whether the extra checks defined below are used when carrying out the decompression. When Strict is on, the extra tests are carried out; when Strict is off, they are not. Default is off.
  • RawInflate => 0|1 — when auto-detecting the compressed format, try to test for raw-deflate (RFC 1951) content using the IO::Uncompress::RawInflate module. The reason this is not default behaviour is because RFC 1951 content can only be detected by attempting to uncompress it. This process is error prone and can result in false positives. Defaults to 0.
  • UnLzma => 0|1 — when auto-detecting the compressed format, try to test for lzma_alone content using the IO::Uncompress::UnLzma module. The reason this is not default behaviour is because lzma_alone content can only be detected by attempting to uncompress it. This process is error prone and can result in false positives. Defaults to 0.

💅 Methods 💅

💖 read (the first one, yes there's two, we'll get to that)

Usage goes a little something like this:

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

So what it does: it reads a block of compressed data — and the size of that block is decided by the Buffer option you set in the constructor — then it uncompresses that block and dumps the uncompressed data into $buffer. And if you set the Append parameter in the constructor, the uncompressed stuff gets appended onto whatever was already in $buffer. If you didn't set it, $buffer gets fully overwritten. no mercy. 💀

It returns the number of uncompressed bytes written into $buffer, or zero if you hit eof, or a negative number on error. periodt.

🦋 read (the second one, the glow-up version)

Usage:

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

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

This one tries to read $length bytes of uncompressed data into $buffer. ✨

The main character difference between this form and the previous one: this one tries to return exactly $length bytes. The only times it won't is if it hits end-of-file or an IO error shows up. That's it, that's the whole exception list.

Returns the number of uncompressed bytes written to $buffer, zero on eof, negative number on error. same energy as before. 🫶

🎀 getline

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

Reads a single line. iconic behaviour honestly.

This method fully supports using the $/ variable (or $INPUT_RECORD_SEPARATOR, or $RS when English is in use — iykyk) to decide what counts as an end of line. Paragraph mode, record mode and file slurp mode? All supported babes. all of them. 🌸

🌈 getc

$char = $z->getc()

Read a single character. just one. tiny.

🧚 ungetc

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

⭐ getHeaderInfo

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

This method hands you back either a hash reference (in scalar context) or a list of hash references (in array context) containing info about every one of the header fields in the compressed data stream(s). Everything you could possibly wanna know about those headers. 📋

💜 tell

$z->tell()
tell $z

Returns the uncompressed file offset. that's the whole vibe.

🔥 eof

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

Returns true if the end of the compressed input stream has been reached. congrats, you made it. 🏁

💅 seek

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

Gives you a sub-set of the seek functionality, with one big restriction: it is only legal to seek forward in the input file/buffer. Trying to seek backward is a fatal error. do not. I'm serious. 😭

Also important: the implementation of seek in this module does not give you true random access to a compressed file/buffer. What it actually does is uncompress data from the current offset in the file/buffer until it reaches the uncompressed offset you specified in the seek parameters. For very small files this might be acceptable behaviour. For large files it may cause an unacceptable delay. so like, know what you're getting into.

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

Returns 1 on success, 0 on failure.

🍓 binmode

$z->binmode
binmode $z ;

This is a noop, provided for completeness. it does nothing. it's here for the vibes. 💀

🌟 opened

$z->opened()

Returns true if the object currently refers to an 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. don't try it. not today.

🦄 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. Do note though that setting the line number does not change the current position within the file/buffer being read. it just changes the number. sneaky.

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 gets called, fileno will return undef. gone. poof.

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

👑 close

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

Closes the output file/buffer.

For most versions of Perl, this method gets automatically invoked if the IO::Uncompress::AnyUncompress object is destroyed — whether that's explicitly or by the variable holding the reference going out of scope. The exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In those cases, the close method will still be called automatically, but not until global destruction of all live objects when the program is terminating. 😬

So therefore: if you want your scripts to run on all versions of Perl, you should call close explicitly and not rely on automatic closing. be proactive babe.

Returns true on success, otherwise 0.

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

🦋 nextStream

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 gets cleared and $. will be reset to 0. fresh start energy. ✨

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

🌸 trailingData

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

Returns the data, if any, that's sitting right there immediately after the compressed data stream once uncompression is complete. It only makes sense to call this method once you've hit the end of the compressed data stream. timing is everything.

This option is useful when there's valuable info immediately following the compressed data stream and you don't know the length of the compressed data stream. mystery data. 🔍

  • 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 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. handy!
  • Don't even bother using trailingData if the input is a filename. fr fr, skip it.

If you know the length of the compressed data stream before you start uncompressing, you can dodge the whole trailingData situation by setting the InputLength option in the constructor. 💡

🛍️ Importing 🛍️

No symbolic constants are required by IO::Uncompress::AnyUncompress at present. none. zero. zip. 💅

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

✨ EXAMPLES ✨

(no examples listed in this page, bestie — go check the other IO::Compress manpages for the goods 🫶)

🫶 SUPPORT 🫶

General feedback, questions and 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. king behaviour honestly. 👑

📜 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 babes, no notes. this was perl v5.44.0, dated 2026-10-17, brought to you by IO::Uncompress::AnyUncompress(3perl) — drink water, call close explicitly, and slay. 💖✨🎀

📦 where this page comes from