1Module::Info(3) User Contributed Perl Documentation Module::Info(3)
2
6 Module::Info - Information about Perl modules
7
9 use Module::Info;
10 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 my @mods = Module::Info->all_installed('Some::Module');
16 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 # 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 # 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 # 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
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
50 Constructors
51 There are a few ways to specify which module you want information for.
52 They all return Module::Info objects.
53 new_from_file
55 my $module = Module::Info->new_from_file('path/to/Some/Module.pm');
56 Given a file, it will interpret this as the module you want
58 information about. You can also hand it a perl script.
59 If the file doesn't exist or isn't readable it will return false.
61 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 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 If you give your own @INC, that will be used to search instead.
71 new_from_loaded
73 my $module = Module::Info->new_from_loaded('Some::Module');
74 Gets information about the currently loaded version of
76 Some::Module. If it isn't loaded, returns false.
77 all_installed
79 my @modules = Module::Info->all_installed('Some::Module');
80 my @modules = Module::Info->all_installed('Some::Module', @INC);
81 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 Information without loading
87 The following methods get their information without actually compiling
88 the module.
89 name
91 my $name = $module->name;
92 $module->name($name);
93 Name of the module (ie. Some::Module).
95 Module loaded using new_from_file() won't have this information in
97 which case you can set it yourself.
98 version
100 my $version = $module->version;
101 Divines the value of $VERSION. This uses the same method as
103 ExtUtils::MakeMaker and all caveats therein apply.
104 inc_dir
106 my $dir = $module->inc_dir;
107 Include directory in which this module was found. Module::Info
109 objects created with new_from_file() won't have this info.
110 file
112 my $file = $module->file;
113 The absolute path to this module.
115 is_core
117 my $is_core = $module->is_core;
118 Checks if this module is the one distributed with Perl.
120 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 has_pod
126 my $has_pod = $module->has_pod;
127 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 Information that requires loading.
133 WARNING! From here down reliability drops rapidly!
134 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 They will only work on 5.6.1 and up and requires the B::Utils module.
140 packages_inside
142 my @packages = $module->packages_inside;
143 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 KNOWN BUG Currently doesn't spot package changes inside
149 subroutines.
150 package_versions
152 my %versions = $module->package_versions;
153 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 modules_used
159 my @used = $module->modules_used;
160 Returns a list of all modules and files which may be "use"'d or
162 "require"'d by this module.
163 NOTE These modules may be conditionally loaded, can't tell. Also
165 can't find modules which might be used inside an "eval".
166 modules_required
168 my %required = $module->modules_required;
169 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 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 NOTE These modules may be conditionally loaded, can't tell. Also
179 can't find modules which might be used inside an "eval".
180 subroutines
182 my %subs = $module->subroutines;
183 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 start => line number of the first statement in the subroutine
190 end => line number of the last statement in the subroutine
191 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 sub foo {
198 package Wibble;
199 $foo = "bar";
200 return $foo;
201 }
202 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 Note this only catches simple "sub foo {...}" subroutine
208 declarations. Anonymous, autoloaded or eval'd subroutines are not
209 listed.
210 superclasses
212 my @isa = $module->superclasses;
213 Returns the value of @ISA for this $module. Requires that
215 $module->name be set to work.
216 NOTE superclasses() is currently cheating. See CAVEATS below.
218 subroutines_called
220 my @calls = $module->subroutines_called;
221 Finds all the methods and functions which are called inside the
223 $module.
224 Returns a list of hashes. Each hash represents a single function
226 or method call and has the keys:
227 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 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 dynamic_method_calls
243 my @methods = $module->dynamic_method_calls;
244 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 Options
250 The following methods get/set specific option values for the
251 Module::Info object.
252 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 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 safe
265 $module->safe(0); # default
266 $module->safe(1); # be safer
267 my $flag = $module->safe;
268 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 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 Sets/gets the "use_version" flag. When the flag is enabled the
279 'version' method always returns a version object.
280
282 <https://github.com/neilb/Module-Info>
283
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 Mattia Barbon <mbarbon@cpan.org> maintained the module from 2002 to
289 2013.
290 Neil Bowers <neilb@cpan.org> is the current maintainer.
292
294 This program is free software; you can redistribute it and/or modify it
295 under the same terms as Perl itself.
296
298 Many thanks to Simon Cozens and Robin Houston for letting me chew their
299 ears about B.
300
302 Code refs in @INC are currently ignored. If this bothers you submit a
303 patch.
304 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 I originally was going to call superclasses() isa() but then I
311 remembered that would be bad.
312 All the methods that require loading are really inefficient as they're
314 not caching anything. I'll worry about efficiency later.
315perl v5.30.1 2020-01-30 Module::Info(3)