Module::Extract(3pm)

💖 Module::Extract — the manual, but make it slay 💖

okay so bestie, this is a page from the User Contributed Perl Documentation — it's Module::Extract(3pm) and it's genuinely one of those little base classes that does the boring stuff so you don't have to. no cap. let's get into it 🫶

---

✨ NAME ✨

Module::Extract — the base class for working with Perl distributions. it's giving "foundation", it's giving "your module's rich auntie who handles the paperwork" 💅

---

🌸 SYNOPSIS 🌸

so you're making a Module::Extract subclass. here's the whole vibe:

package My::Readme;

# Shows the README file for a module

use strict;
use base 'Module::Extract';

sub show {
    my $self   = shift;
    my $readme = $self->file_path('README');
    if ( -f $readme ) {
        system( "cat $readme" );
    } else {
        print "Dist does not have a README file";
    }
}

1;

and then a little script that uses it to show the readme for whatever distribution filename the user hands over 🎀

#!/usr/bin/perl

use My::Readme;

My::Readme->new( dist_file => $ARGV[0] )->show;

exit(0);

---

🦋 DESCRIPTION 🦋

Module::Extract is a convenience base class for creating modules that work with Perl distributions. it's the lowkey hero energy of the CPAN world ✨

its whole purpose? to take care of the mechanisms of locating and extracting a Perl distribution, so that your module can go do something specific to that distribution. you focus on the fun part, it handles the logistics. iconic division of labour, honestly 👑

this module was originally created to provide an abstraction for the extraction logic for both Module::Inspector and Module::P4P, and to allow additional features to be added in the future without having to modify both of them. because the general problem of "locate, download, and expand a distribution" is one that is almost ideal for adding additional features down the line. future-proofing, periodt 💜

💫 new

my $from_file = My::Class->new(
    dist_file => 'tarball.tar.gz',
    );

my $from_dir = My::Class->new(
    dist_dir  => 'some/dir',
    );

the new constructor takes a dist_file and/or a dist_dir param, locates and (if needed) expands the distribution tarball.

it takes either a dist_file param — which should be the local path to the tarball — or a dist_dir, which should be the path to a directory containing an already-expanded distribution (like from a repository checkout, iykyk).

returns a shiny new Module::Extract-subclass object, or dies on error 💀

💫 dist_file

the dist_file accessor returns the (absolute) path to the distribution tarball. but heads up — if the inspector was created with dist_dir rather than dist_file, this will return undef. sad but true 😭

💫 dist_type

the dist_type method returns the archive type of the distribution tarball. this will be either 'tar.gz', 'tgz', or 'zip'. other file types are not supported at this time — so don't come for it 🚫

and again: if the inspector was created with dist_dir rather than dist_file, this will return undef.

💫 dist_dir

the dist_dir method returns the (absolute) distribution root directory 🌳

if the inspector was created with dist_file rather than dist_file, this method will return the temporary directory created to hold the unwrapped tarball. (yes, the original says dist_file twice there — we're reporting it faithfully, no edits, that's the rule 🫡)

💫 file_path

my $local_path = $inspector->file_path('lib/Foo.pm');

to simplify implementations, most tools that work with distributions identify files in unix-style relative paths. love that for them.

the file_path method takes a unix-style relative path and returns a localised absolute path to the file on disk — either in the actual distribution directory, or the temp directory holding the expanded tarball. either way, you get your file 🍓

💫 dir_path

my $local_path = $inspector->file_path('lib');

the dir_path method is the matching pair of the file_path method. soulmates, fr fr 🫶

just like that method, it takes a unix-style relative directory name, and returns a localised absolute path to the directory.

---

🌈 SUPPORT 🌈

this module is stored in an Open Repository at the following address:

<http://svn.phase-n.com/svn/cpan/trunk/Module-Extract>

write access to the repository is made available automatically to any published CPAN author, and to most other volunteers on request. come through 💅

if you are able to submit your bug report in the form of new (failing) unit tests, or can apply your fix directly instead of submitting a patch, you are strongly encouraged to do so — because the author currently maintains over 100 modules and it can take some time to deal with non-Critcal bug reports or patches. (that's "Critcal" with the typo, verbatim, we don't touch it 🙈)

this will guarentee that your issue will be addressed in the next release of the module. (also verbatim. the typos are load-bearing, bestie 😭)

if you cannot provide a direct test or fix, or don't have time to do so, then regular bug reports are still accepted and appreciated via the CPAN bug tracker:

<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Module-Extract>

for other issues, for commercial enhancement or support, or to have your write access enabled for the repository, contact the author at the email address above 📧

---

👑 AUTHORS 👑

Adam Kennedy <adamk@cpan.org>

---

⭐ SEE ALSO ⭐

• Module::Inspector
• Module::P4P

---

🎀 COPYRIGHT 🎀

Copyright 2006 Adam Kennedy.

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

the full text of the license can be found in the LICENSE file included with this module.

---

💖 okay that's the whole page! go forth and extract some distributions, bestie. you're gonna do amazing.

perl v5.34.0 · 2022-06-15 — that's the version and date this page shipped with, and that's a wrap 🧚✨