1Module::Inspector(3) User Contributed Perl Documentation Module::Inspector(3)
2
6 Module::Inspector - An integrated API for inspecting Perl distributions
7
9 An entire ecosystem of CPAN modules exist around the files and formats
10 relating to the CPAN itself. Parsers and object models for various
11 different types of files have been created over the years by various
12 people for various projects.
13 These modules have a variety of different styles, and work in various
15 different ways.
16 So when it comes to analysing the structure of a Perl module (either
18 inside a repository, in a tarball, or in unpacked form) it is certainly
19 quite possible to do.
20 It's just that often it takes a high level of experience with the
22 various modules in question, and the knowledge of how to combine the
23 dozen of so modules in one cohesive program.
24 Personally, I have always found this laborious.
26 What I would prefer is a single API that is easy to use, implements the
28 magic invisibly behind the scenes, and co-ordinates the use of the
29 various modules for me as needed.
30 Module::Inspector provides such an API, and provides a companion to the
32 Class::Inspector API for accessing information on class after
33 installation.
34 It provides a wrapper around the various modules used to read and
36 examine the different parts of a Perl module distribution tarball, and
37 can inspect a module unrolled on disk, in a repository checkout, or
38 just look directly inside a tarball.
39
41 new
42 # Inspect a plain dist directory or cvs/svn checkout
43 my $dir = Module::Inspector->new(
44 dist_dir => $dirpath,
45 );
46 # Inspect a tarball
48 my $file = Module::Inspector->new(
49 dist_file => 'Foo-Bar-0.01.tar.gz',
50 );
51 The "new" constructor creates a new module inspector. It takes a named
53 param of either "dist_file", which should be the file path of the dist
54 tarball, or "dist_dir", which is the root of the distribution directory
55 (if it is already unrolled).
56 The distribution will be quickly pre-scanned to locate the various
58 significant documents in the distribution (although only a few are
59 initially supported).
60 Returns a new "Module::Inspector" object, or dies on exception.
62 version_control
64 my $vcs_type = $self->version_control;
65 For reasons that will hopefully be more apparant later,
67 Module::Inspector detects any version control system in use within the
68 "dist_dir" for the module.
69 Currently, support is limited to detection of CVS and Subversion.
71 Returns a the name of the version control system detected in use as a
73 string (currently 'cvs' or 'svn'). If no version control is able to be
74 detected returns the null string ''.
75 documents
77 The "documents" method returns a list of the names of all the documents
78 detected by the "Module::Inspector".
79 In scalar context, returns the number of identifyable documens found in
81 the distribution.
82 document_type
84 # Returns 'PPI::Document::File'
85 my $ppi_class = $inspector->document_type('lib/Foo.pm');
86 In Module::Inspector, all documents are represented as objects.
88 Thus, for each different type of document, there is going to be a
90 different class that implements the document objects for that type.
91 The "document_type" method returns the type for a provided document as
93 a class name.
94 Please note that at this time these document types are not necesarily
96 stable, and over the first several releases I may need to change the
97 class I'm using to represent a particular document type.
98 document
100 my $perl = $inspector->document('lib/Foo.pm');
101 The "document" method returns the document object for a named file,
103 loading and caching it on the fly if needed.
104 The type of object will vary depending on the document.
106 For example, a Perl file will be returned as a PPI::Document, a
108 MANIFEST file as a Module::Manifest, and so on.
109 Returns an object, or dies on error.
111 dist_name
113 # Returns Config-Tiny
114 my $name = $inspector->dist_name;
115 The "dist_name" method returns the name of the distribution, as
117 determined from the META.yml file.
118 Returns the name as a string, or dies on error.
120 dist_version
122 The "dist_version" method returns the version of the distribution, as
123 determined from the META.yml file in the distribution.
124 Returns a version object, or dies on error.
126 dist_requires
128 my $depends = $inspector->dist_requires;
129 The "dist_requires" method checks for any run-time dependencies of the
131 distribution and returns them as a Module::Math::Depends object.
132 See the docs for Module::Math::Depends for more information on its
134 structure and API.
135 If the distribution has no run-time dependencies, the object will still
137 be returned, but will be empty.
138 Returns a single Module::Math::Depends object, or dies on error.
140 dist_build_requires
142 The "dist_build_requires" method returns the build-time-only
143 dependencies of the distribution.
144 If there are no build-time dependencies, the object will still be
146 returned, but will be empty.
147 Returns a Module::Math::Depends object, or dies on exception.
149 dist_depends
151 The "dist_depends" method returns as for the two methods above
152 ("dist_requires" and "dist_build_requires") except that this method
153 returns a merged dependency object, representing BOTH the install-time
154 and run-time dependencies for the distribution.
155 If there are no build-time or run-time dependencies, the object will be
157 returned, but will be empty.
158 Returns a Module::Math::Depends object, or dies on error.
160
162 - Implement most of the functionality
163
165 This module is stored in an Open Repository at the following address.
166 http://svn.ali.as/cpan/trunk/Module-Inspector
168 <http://svn.ali.as/cpan/trunk/Module-Inspector>
169 Write access to the repository is made available automatically to any
171 published CPAN author, and to most other volunteers on request.
172 If you are able to submit your bug report in the form of new (failing)
174 unit tests, or can apply your fix directly instead of submitting a
175 patch, you are strongly encouraged to do so as the author currently
176 maintains over 100 modules and it can take some time to deal with non-
177 Critcal bug reports or patches.
178 This will guarentee that your issue will be addressed in the next
180 release of the module.
181 If you cannot provide a direct test or fix, or don't have time to do
183 so, then regular bug reports are still accepted and appreciated via the
184 CPAN bug tracker.
185 http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Module-Inspector
187 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Module-Inspector>
188 For other issues, for commercial enhancement or support, or to have
190 your write access enabled for the repository, contact the author at the
191 email address above.
192
194 Adam Kennedy <adamk@cpan.org>
195
197 Class::Inspector
198
200 Copyright 2006 - 2008 Adam Kennedy.
201 This program is free software; you can redistribute it and/or modify it
203 under the same terms as Perl itself.
204 The full text of the license can be found in the LICENSE file included
206 with this module.
207perl v5.12.0 2008-08-16 Module::Inspector(3)