Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
Module::Inspector(3)  User Contributed Perl Documentation Module::Inspector(3)

       Module::Inspector - An integrated API for inspecting Perl distributions

       An entire ecosystem of CPAN modules exist around	the files and formats
       relating	to the CPAN itself. Parsers and	object models for various
       different types of files	have been created over the years by various
       people for various projects.

       These modules have a variety of different styles, and work in various
       different ways.

       So when it comes	to analysing the structure of a	Perl module (either
       inside a	repository, in a tarball, or in	unpacked form) it is certainly
       quite possible to do.

       It's just that often it takes a high level of experience	with the
       various modules in question, and	the knowledge of how to	combine	the
       dozen of	so modules in one cohesive program.

       Personally, I have always found this laborious.

       What I would prefer is a	single API that	is easy	to use,	implements the
       magic invisibly behind the scenes, and co-ordinates the use of the
       various modules for me as needed.

       Module::Inspector provides such an API, and provides a companion	to the
       Class::Inspector	API for	accessing information on class after

       It provides a wrapper around the	various	modules	used to	read and
       examine the different parts of a	Perl module distribution tarball, and
       can inspect a module unrolled on	disk, in a repository checkout,	or
       just look directly inside a tarball.

	 # 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. 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
       (if it is already unrolled).

       The distribution	will be	quickly	pre-scanned to locate the various
       significant documents in	the distribution (although only	a few are
       initially supported).

       Returns a new "Module::Inspector" object, or dies on exception.

	 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 a the name of the version control system	detected in use	as a
       string (currently 'cvs' or 'svn'). If no	version	control	is able	to be
       detected	returns	the null string	''.

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

       In scalar context, returns the number of	identifyable documens found in
       the distribution.

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

       In Module::Inspector, all documents are represented as objects.

       Thus, for each different	type of	document, there	is going to 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 I may need to change	the
       class I'm using to represent a particular document type.

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

       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.

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

       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.

	 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 information on its
       structure and API.

       If the distribution has no run-time dependencies, the object will still
       be returned, but	will be	empty.

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

       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.

       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.

       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.

       - Implement most	of the functionality

       This module is stored in	an Open	Repository at the following address.


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


       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.

       Adam Kennedy <>


       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.

perl v5.32.1			  2008-08-16		  Module::Inspector(3)


Want to link to this manual page? Use this URL:

home | help