CPAN::P...ribution(3)

💖 CPAN::ParseDistribution — the manual, but make it cute ✨

okay bestie, gather round, because this is the CPAN::ParseDistribution page and it is lowkey iconic 🫶

---

🌸 NAME 🌸

CPAN::ParseDistribution — index a file from the BackPAN

---

🦋 DESCRIPTION 🦋

so like, you hand this thing a file from the BackPAN, and it tells you what versions of what modules live inside it, plus the distribution name and the distribution version. that's it. that's the whole vibe. no cap ✨

---

🎀 SYNOPSIS 🎀

my $dist = CPAN::ParseDistribution->new(
    'A/AU/AUTHORID/subdirectory/Some-Distribution-1.23.tar.gz',
    use_tar => '/bin/tar',
    ...
);
my $modules     = $dist->modules(); # hashref of modname => version
my $distname    = $dist->dist();
my $distversion = $dist->distversion();

---

💅 METHODS 💅

🌈 new

Constructor bestie!! 🎉 It takes a single mandatory argument, which should be a tarball or zip file from the CPAN or BackPAN, and then some optional named arguments:

• use_tar — the full path to tar. it's assumed to be GNU tar, and assumed to be sufficiently well-endowed as to be able to support bzip2 files 🙈 maybe that'll get fixed at some point, who knows. If you don't specify this, then Archive::Tar gets used instead.

You might wanna reach for this one if you're dealing with very large files, because Archive::Tar is rather profligate with memory. it's giving "will eat your RAM for breakfast" 😭

⭐ isdevversion

Returns true or false depending on whether this is a developer-only or trial release of a distribution. how does it know?? it's looking for an underscore in the distribution version, or the string '-TRIAL' at the end of the distribution version. detective behaviour fr fr 🕵️♀️

🍓 modules

Returns a hashref whose keys are module names, and whose values are the versions of the modules. the version number gets retrieved by eval()ing what looks like a $VERSION line in the code. this happens in a "Safe" compartment, but it may be a security risk if you do this with untrusted code. Caveat user! 💀

🧚 dist

Return the name of the distribution. eg, in the synopsis above, it would return 'Some-Distribution'. slay ✨

👑 distversion

Return the version of the distribution. eg, in the synopsis above, it would return 1.23.

Strictly speaking, the CPAN doesn't have distribution versions — Foo-Bar-1.23.tar.gz is not considered to have any relationship to Foo-Bar-1.24.tar.gz, they just happen to coincidentally have rather similar contents 🙃 But other tools, such as those used by the CPAN testers, do treat distributions as being versioned.

---

🔥 SECURITY 🔥

okay so this is the serious one, bestie, listen up 🫶

This module executes a very small amount of code from each module that it finds in a distribution. While every effort has been made to do this safely, there are no guarantees that it won't let the distributions you're examining do horrible things to your machine, such as email your password file to strangers 😭😭

You are strongly advised to read the source code and to run it in a very heavily restricted user account. periodt. 💅

---

💜 LIMITATIONS, BUGS and FEEDBACK 💜

I welcome feedback about my code, including constructive criticism 🫶 Bug reports should be made using Github Issues <https://github.com/DrHyde/perl-modules-CPAN-ParseDistribution/issues> and should include the smallest possible chunk of code, along with any necessary data, which demonstrates the bug. Ideally, this will be in the form of files which I can drop in to the module's test suite ✨

There is a known problem with parsing some pathological distributions on Windows, where CPAN::ParseDistribution may either hang or crash 💀 This is because Windows doesn't properly support fork()ing and signals. I can not fix this, but welcome patches with tests 🙈

---

🦄 SEE ALSO 🦄

• <http://pause.perl.org/>
• dumpcpandist

---

🎀 AUTHOR, COPYRIGHT and LICENCE 🎀

Copyright 2009-2011 David Cantrell <david@cantrell.org.uk>

Contains code originally from the PAUSE by Andreas Koenig.

This software is free-as-in-speech software, and may be used, distributed, and modified under the terms of either the GNU General Public Licence version 2 or the Artistic Licence. It's up to you which one you use. The full text of the licences can be found in the files GPL2.txt and ARTISTIC.txt, respectively.

---

🌈 CONSPIRACY 🌈

This module is also free-as-in-mason software. 🧱✨

---

and that's the whole page, bestie!! this was perl v5.42.0, dated 2025-07-25, and it's the CPAN::P...ribution(3) manual — mwah, ily, go read some source code before you run it on untrusted stuff, k? 💖🦋🎀