Module...spector(3pm)

💖 Module::Inspector — the manual, but make it cute 💖

okay bestie, so this is Module::Inspector (you'll see it written as Module...spector(3pm) in the header up top, that's just how the man page gets truncated, don't panic 🫶). It's Perl, it's user-contributed documentation, and it's about to make your whole CPAN-archaeology era so much easier. let's go. ✨

---

✨ NAME ✨

Module::Inspector — an integrated API for inspecting Perl distributions. like, the integrated API. slay. 👑

---

🌸 DESCRIPTION 🌸

so here's the tea, bestie. 🍓 There is an entire ecosystem of CPAN modules out there floating around the files and formats that relate to the CPAN itself. parsers, object models, all sorts of different file-type machinery — built up over the years by all sorts of different people for all sorts of different projects.

and the problem is: these modules have a variety of different styles, and they work in a variety of different ways. iconic of them honestly, but also kind of a lot. 🙈

so when you want to analyse the structure of a Perl module — whether it's sitting inside a repository, chilling in a tarball, or already unpacked on disk — it's certainly quite possible to do it. no cap.

it's just that... it often takes a high level of experience with all the various modules in question, plus the knowledge of how to stitch a dozen-or-so of them together into one cohesive program. and that, bestie, is giving homework. 😭

personally, the author has always found this laborious. and honestly? valid.

what they'd prefer is a single API that is easy to use, that implements the magic invisibly behind the scenes, and that co-ordinates the use of the various modules for you as needed. main character energy for an API, and we're obsessed. 💅

Module::Inspector provides exactly that API ✨ — and it's a companion to the Class::Inspector API, which handles accessing information on a class after installation.

basically it's a wrapper around the various modules used to read and examine the different parts of a Perl module distribution tarball, and it can inspect:

• a module unrolled on disk
• a repository checkout
• or just look directly inside a tarball 🎀

---

💅 METHODS 💅

🌈 new 🌈

# Inspect a plain dist directory or cvs/svn checkout
my $dir = Module::Inspector->new(
        dist_dir => $dirpath,
        );

# Inspect a tarball
my $file = Module::Inspector->new(
        dist_file => 'Foo-Bar-0.01.tar.gz',
        );

the new constructor creates a new module inspector, bestie. 🫶 it takes a named param of either:

• dist_file — which should be the file path of the dist tarball, or
• dist_dir — which is the root of the distribution directory (use this if it's already unrolled)

the distribution gets a quick little pre-scan to locate the various significant documents inside it (though, ngl, only a few are initially supported at this point).

returns a new Module::Inspector object, or dies on exception. ⭐

---

🦋 version_control 🦋

my $vcs_type = $self->version_control;

for reasons that will hopefully be more apparant later 👀, Module::Inspector detects any version control system in use within the dist_dir for the module.

currently, support is limited to detection of CVS and Subversion.

returns the name of the version control system detected in use as a string (currently 'cvs' or 'svn'). and if no version control is able to be detected, it returns the null string ''. 💀

---

🎀 documents 🎀

the documents method returns a list of the names of all the documents detected by the Module::Inspector.

in scalar context, it returns the number of identifyable documens found in the distribution. (yes, count them, bestie ✨)

---

💜 document_type 💜

# Returns 'PPI::Document::File'
my $ppi_class = $inspector->document_type('lib/Foo.pm');

in Module::Inspector, all documents are represented as objects. periodt.

so, for each different type of document, there's gonna be a different class that implements the document objects for that type. 🌈

the document_type method returns the type for a provided document as a class name.

⚠️ please note that at this time these document types are not necesarily stable, and over the first several releases the author may need to change the class being used to represent a particular document type. so like, don't hardcode your whole personality around it. 😭

---

🧚 document 🧚

my $perl = $inspector->document('lib/Foo.pm');

the document method returns the document object for a named file, loading and caching it on the fly if needed. 🍓

the type of object will vary depending on the document. for example:

• a Perl file will be returned as a PPI::Document
• a MANIFEST file as a Module::Manifest
• and so on ✨

returns an object, or dies on error.

---

👑 dist_name 👑

# Returns Config-Tiny
my $name = $inspector->dist_name;

the dist_name method returns the name of the distribution, as determined from the META.yml file. 💖

returns the name as a string, or dies on error.

---

🌸 dist_version 🌸

the dist_version method returns the version of the distribution, as determined from the META.yml file in the distribution.

returns a version object, or dies on error.

---

⭐ dist_requires ⭐

my $depends = $inspector->dist_requires;

the dist_requires method checks for any run-time dependencies of the distribution and returns them as a Module::Math::Depends object. 🫶

see the docs for Module::Math::Depends for more info on its structure and API.

if the distribution has no run-time dependencies, the object will still be returned — it'll just be empty. (iconic of it, honestly.)

returns a single Module::Math::Depends object, or dies on error.

---

💖 dist_build_requires 💖

the dist_build_requires method returns the build-time-only dependencies of the distribution.

if there are no build-time dependencies, the object will still be returned, but will be empty. 🌈

returns a Module::Math::Depends object, or dies on exception.

---

🔥 dist_depends 🔥

the dist_depends method returns as for the two methods above (dist_requires and dist_build_requires) — except that this method returns a merged dependency object, representing BOTH the install-time and run-time dependencies for the distribution. the way that it merges both?? ate. 💅

if there are no build-time or run-time dependencies, the object will be returned, but will be empty.

returns a Module::Math::Depends object, or dies on error.

---

🙈 TO DO 🙈

• Implement most of the functionality

(no notes, bestie. that's the whole list. the honesty is lowkey breathtaking. 💀)

---

🫶 SUPPORT 🫶

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

http://svn.ali.as/cpan/trunk/Module-Inspector

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

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. 😭

this will guarentee that your issue will be addressed in the next release of the module. ✨

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-Inspector

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. 💜

---

🌟 AUTHOR 🌟

Adam Kennedy <adamk@cpan.org>

---

💫 SEE ALSO 💫

Class::Inspector

---

🎀 COPYRIGHT 🎀

Copyright 2006 - 2008 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.

---

and that's a wrap, bestie!! 💅 this page came from perl v5.34.0 and it was dated 2022-06-15 — so if you're reading this in the future, hello from the past, hope you slayed. 👑✨💖