1Module::Inspector(3)  User Contributed Perl Documentation Module::Inspector(3)
2
3
4

NAME

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

DESCRIPTION

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
14       These modules have a variety of different styles, and work in various
15       different ways.
16
17       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
21       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
25       Personally, I have always found this laborious.
26
27       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
31       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
35       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

METHODS

41   new
42         # Inspect a plain dist directory or cvs/svn checkout
43         my $dir = Module::Inspector->new(
44                 dist_dir => $dirpath,
45                 );
46
47         # Inspect a tarball
48         my $file = Module::Inspector->new(
49                 dist_file => 'Foo-Bar-0.01.tar.gz',
50                 );
51
52       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
57       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
61       Returns a new "Module::Inspector" object, or dies on exception.
62
63   version_control
64         my $vcs_type = $self->version_control;
65
66       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
70       Currently, support is limited to detection of CVS and Subversion.
71
72       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
76   documents
77       The "documents" method returns a list of the names of all the documents
78       detected by the "Module::Inspector".
79
80       In scalar context, returns the number of identifyable documens found in
81       the distribution.
82
83   document_type
84         # Returns 'PPI::Document::File'
85         my $ppi_class = $inspector->document_type('lib/Foo.pm');
86
87       In Module::Inspector, all documents are represented as objects.
88
89       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
92       The "document_type" method returns the type for a provided document as
93       a class name.
94
95       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
99   document
100         my $perl = $inspector->document('lib/Foo.pm');
101
102       The "document" method returns the document object for a named file,
103       loading and caching it on the fly if needed.
104
105       The type of object will vary depending on the document.
106
107       For example, a Perl file will be returned as a PPI::Document, a
108       MANIFEST file as a Module::Manifest, and so on.
109
110       Returns an object, or dies on error.
111
112   dist_name
113         # Returns Config-Tiny
114         my $name = $inspector->dist_name;
115
116       The "dist_name" method returns the name of the distribution, as
117       determined from the META.yml file.
118
119       Returns the name as a string, or dies on error.
120
121   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
125       Returns a version object, or dies on error.
126
127   dist_requires
128         my $depends = $inspector->dist_requires;
129
130       The "dist_requires" method checks for any run-time dependencies of the
131       distribution and returns them as a Module::Math::Depends object.
132
133       See the docs for Module::Math::Depends for more information on its
134       structure and API.
135
136       If the distribution has no run-time dependencies, the object will still
137       be returned, but will be empty.
138
139       Returns a single Module::Math::Depends object, or dies on error.
140
141   dist_build_requires
142       The "dist_build_requires" method returns the build-time-only
143       dependencies of the distribution.
144
145       If there are no build-time dependencies, the object will still be
146       returned, but will be empty.
147
148       Returns a Module::Math::Depends object, or dies on exception.
149
150   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
156       If there are no build-time or run-time dependencies, the object will be
157       returned, but will be empty.
158
159       Returns a Module::Math::Depends object, or dies on error.
160

TO DO

162       - Implement most of the functionality
163

SUPPORT

165       This module is stored in an Open Repository at the following address.
166
167       http://svn.ali.as/cpan/trunk/Module-Inspector
168       <http://svn.ali.as/cpan/trunk/Module-Inspector>
169
170       Write access to the repository is made available automatically to any
171       published CPAN author, and to most other volunteers on request.
172
173       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
179       This will guarentee that your issue will be addressed in the next
180       release of the module.
181
182       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
186       http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Module-Inspector
187       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Module-Inspector>
188
189       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

AUTHOR

194       Adam Kennedy <adamk@cpan.org>
195

SEE ALSO

197       Class::Inspector
198
200       Copyright 2006 - 2008 Adam Kennedy.
201
202       This program is free software; you can redistribute it and/or modify it
203       under the same terms as Perl itself.
204
205       The full text of the license can be found in the LICENSE file included
206       with this module.
207
208
209
210perl v5.12.0                      2008-08-16              Module::Inspector(3)
Impressum