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

NAME

6       Module::Info - Information about Perl modules
7

SYNOPSIS

9         use Module::Info;
10
11         my $mod = Module::Info->new_from_file('Some/Module.pm');
12         my $mod = Module::Info->new_from_module('Some::Module');
13         my $mod = Module::Info->new_from_loaded('Some::Module');
14
15         my @mods = Module::Info->all_installed('Some::Module');
16
17         my $name    = $mod->name;
18         my $version = $mod->version;
19         my $dir     = $mod->inc_dir;
20         my $file    = $mod->file;
21         my $is_core = $mod->is_core;
22
23         # Only available in perl 5.6.1 and up.
24         # These do compile the module.
25         my @packages = $mod->packages_inside;
26         my @used     = $mod->modules_used;
27         my @subs     = $mod->subroutines;
28         my @isa      = $mod->superclasses;
29         my @calls    = $mod->subroutines_called;
30
31         # Check for constructs which make perl hard to predict.
32         my @methods   = $mod->dynamic_method_calls;
33         my @lines     = $mod->eval_string;    *UNIMPLEMENTED*
34         my @lines     = $mod->gotos;          *UNIMPLEMENTED*
35         my @controls  = $mod->exit_via_loop_control;      *UNIMPLEMENTED*
36         my @unpredictables = $mod->has_unpredictables;    *UNIMPLEMENTED*
37
38         # set/get Module::Info options
39         $self->die_on_compilation_error(1);
40         my $die_on_error = $mod->die_on_compilation_error;
41         $self->safe(1);
42         my $safe = $mod->safe;
43

DESCRIPTION

45       Module::Info gives you information about Perl modules without actually
46       loading the module.  It actually isn't specific to modules and should
47       work on any perl code.
48

METHODS

50   Constructors
51       There are a few ways to specify which module you want information for.
52       They all return Module::Info objects.
53
54       new_from_file
55             my $module = Module::Info->new_from_file('path/to/Some/Module.pm');
56
57           Given a file, it will interpret this as the module you want
58           information about.  You can also hand it a perl script.
59
60           If the file doesn't exist or isn't readable it will return false.
61
62       new_from_module
63             my $module = Module::Info->new_from_module('Some::Module');
64             my $module = Module::Info->new_from_module('Some::Module', @INC);
65
66           Given a module name, @INC will be searched and the first module
67           found used.  This is the same module that would be loaded if you
68           just say "use Some::Module".
69
70           If you give your own @INC, that will be used to search instead.
71
72       new_from_loaded
73             my $module = Module::Info->new_from_loaded('Some::Module');
74
75           Gets information about the currently loaded version of
76           Some::Module.  If it isn't loaded, returns false.
77
78       all_installed
79             my @modules = Module::Info->all_installed('Some::Module');
80             my @modules = Module::Info->all_installed('Some::Module', @INC);
81
82           Like new_from_module(), except all modules in @INC will be
83           returned, in the order they are found.  Thus $modules[0] is the one
84           that would be loaded by "use Some::Module".
85
86   Information without loading
87       The following methods get their information without actually compiling
88       the module.
89
90       name
91             my $name = $module->name;
92             $module->name($name);
93
94           Name of the module (ie. Some::Module).
95
96           Module loaded using new_from_file() won't have this information in
97           which case you can set it yourself.
98
99       version
100             my $version = $module->version;
101
102           Divines the value of $VERSION.  This uses the same method as
103           ExtUtils::MakeMaker and all caveats therein apply.
104
105       inc_dir
106             my $dir = $module->inc_dir;
107
108           Include directory in which this module was found.  Module::Info
109           objects created with new_from_file() won't have this info.
110
111       file
112             my $file = $module->file;
113
114           The absolute path to this module.
115
116       is_core
117             my $is_core = $module->is_core;
118
119           Checks if this module is the one distributed with Perl.
120
121           NOTE This goes by what directory it's in.  It's possible that the
122           module has been altered or upgraded from CPAN since the original
123           Perl installation.
124
125       has_pod
126               my $has_pod = $module->has_pod;
127
128           Returns the location of the module's pod, which can be the module
129           file itself, if the POD is inlined, the associated POD file, or
130           nothing if there is no POD at all.
131
132   Information that requires loading.
133       WARNING!  From here down reliability drops rapidly!
134
135       The following methods get their information by compiling the module and
136       examining the opcode tree.  The module will be compiled in a separate
137       process so as not to disturb the current program.
138
139       They will only work on 5.6.1 and up and requires the B::Utils module.
140
141       packages_inside
142             my @packages = $module->packages_inside;
143
144           Looks for any explicit "package" declarations inside the module and
145           returns a list.  Useful for finding hidden classes and
146           functionality (like Tie::StdHandle inside Tie::Handle).
147
148           KNOWN BUG Currently doesn't spot package changes inside
149           subroutines.
150
151       package_versions
152             my %versions = $module->package_versions;
153
154           Returns a hash whose keys are the packages contained in the module
155           (these are the same as what's returned by "packages_inside()"), and
156           whose values are the versions of those packages.
157
158       modules_used
159             my @used = $module->modules_used;
160
161           Returns a list of all modules and files which may be "use"'d or
162           "require"'d by this module.
163
164           NOTE These modules may be conditionally loaded, can't tell.  Also
165           can't find modules which might be used inside an "eval".
166
167       modules_required
168             my %required = $module->modules_required;
169
170           Returns a list of all modules and files which may be "use"'d or
171           "require"'d by this module, together with the minimum required
172           version.
173
174           The hash is keyed on the module/file name, the corrisponding value
175           is an array reference containing the requied versions, or an empty
176           array if no specific version was required.
177
178           NOTE These modules may be conditionally loaded, can't tell.  Also
179           can't find modules which might be used inside an "eval".
180
181       subroutines
182             my %subs = $module->subroutines;
183
184           Returns a hash of all subroutines defined inside this module and
185           some info about it.  The key is the *full* name of the subroutine
186           (ie. $subs{'Some::Module::foo'} rather than just $subs{'foo'}),
187           value is a hash ref with information about the subroutine like so:
188
189               start   => line number of the first statement in the subroutine
190               end     => line number of the last statement in the subroutine
191
192           Note that the line numbers may not be entirely accurate and will
193           change as perl's backend compiler improves.  They typically
194           correspond to the first and last run-time statements in a
195           subroutine.  For example:
196
197               sub foo {
198                   package Wibble;
199                   $foo = "bar";
200                   return $foo;
201               }
202
203           Taking "sub foo {" as line 1, Module::Info will report line 3 as
204           the start and line 4 as the end.  "package Wibble;" is a compile-
205           time statement.  Again, this will change as perl changes.
206
207           Note this only catches simple "sub foo {...}" subroutine
208           declarations.  Anonymous, autoloaded or eval'd subroutines are not
209           listed.
210
211       superclasses
212             my @isa = $module->superclasses;
213
214           Returns the value of @ISA for this $module.  Requires that
215           $module->name be set to work.
216
217           NOTE superclasses() is currently cheating.  See CAVEATS below.
218
219       subroutines_called
220             my @calls = $module->subroutines_called;
221
222           Finds all the methods and functions which are called inside the
223           $module.
224
225           Returns a list of hashes.  Each hash represents a single function
226           or method call and has the keys:
227
228               line        line number where this call originated
229               class       class called on if its a class method
230               type        function, symbolic function, object method,
231                           class method, dynamic object method or
232                           dynamic class method.
233                           (NOTE  This format will probably change)
234               name        name of the function/method called if not dynamic
235
236   Information about Unpredictable Constructs
237       Unpredictable constructs are things that make a Perl program hard to
238       predict what its going to do without actually running it.  There's
239       nothing wrong with these constructs, but its nice to know where they
240       are when maintaining a piece of code.
241
242       dynamic_method_calls
243             my @methods = $module->dynamic_method_calls;
244
245           Returns a list of dynamic method calls (ie. "$obj-"$method()>) used
246           by the $module.  @methods has the same format as the return value
247           of subroutines_called().
248
249   Options
250       The following methods get/set specific option values for the
251       Module::Info object.
252
253       die_on_compilation_error
254             $module->die_on_compilation_error(0); # default
255             $module->die_on_compilation_error(1);
256             my $flag = $module->die_on_compilation_error;
257
258           Sets/gets the "die on compilation error" flag. When the flag is off
259           (default), and a module fails to compile, Module::Info simply emits
260           a watning and continues. When the flag is on and a module fails to
261           compile, Module::Info "die()"s with the same error message it would
262           use in the warning.
263
264       safe
265             $module->safe(0); # default
266             $module->safe(1); # be safer
267             my $flag = $module->safe;
268
269           Sets/gets the "safe" flag. When the flag is enabled all operations
270           requiring module compilation are forbidden and the "version()"
271           method executes its code in a "Safe" compartment.
272
273       use_version
274             $module->use_version(0); # do not use version.pm (default)
275             $module->use_version(1); # use version.pm, die if not present
276             my $flag = $module->use_version;
277
278           Sets/gets the "use_version" flag. When the flag is enabled the
279           'version' method always returns a version object.
280

REPOSITORY

282       <https://github.com/neilb/Module-Info>
283

AUTHOR

285       Michael G Schwern <schwern@pobox.com> with code from ExtUtils::MM_Unix,
286       Module::InstalledVersion and lots of cargo-culting from B::Deparse.
287
288       Mattia Barbon <mbarbon@cpan.org> maintained the module from 2002 to
289       2013.
290
291       Neil Bowers <neilb@cpan.org> is the current maintainer.
292

LICENSE

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

THANKS

298       Many thanks to Simon Cozens and Robin Houston for letting me chew their
299       ears about B.
300

CAVEATS

302       Code refs in @INC are currently ignored.  If this bothers you submit a
303       patch.
304
305       superclasses() is cheating and just loading the module in a separate
306       process and looking at @ISA.  I don't think its worth the trouble to go
307       through and parse the opcode tree as it still requires loading the
308       module and running all the BEGIN blocks.  Patches welcome.
309
310       I originally was going to call superclasses() isa() but then I
311       remembered that would be bad.
312
313       All the methods that require loading are really inefficient as they're
314       not caching anything.  I'll worry about efficiency later.
315
316
317
318perl v5.30.1                      2020-01-30                   Module::Info(3)
Impressum