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.
53 They all return Module::Info objects.
54 new_from_file
56 my $module = Module::Info->new_from_file('path/to/Some/Module.pm');
57 Given a file, it will interpret this as the module you want infor‐
59 mation about. You can also hand it a perl script.
60 If the file doesn't exist or isn't readable it will return false.
62 new_from_module
64 my $module = Module::Info->new_from_module('Some::Module');
65 my $module = Module::Info->new_from_module('Some::Module', @INC);
66 Given a module name, @INC will be searched and the first module
68 found used. This is the same module that would be loaded if you
69 just say "use Some::Module".
70 If you give your own @INC, that will be used to search instead.
72 new_from_loaded
74 my $module = Module::Info->new_from_loaded('Some::Module');
75 Gets information about the currently loaded version of Some::Mod‐
77 ule. If it isn't loaded, returns false.
78 all_installed
80 my @modules = Module::Info->all_installed('Some::Module');
81 my @modules = Module::Info->all_installed('Some::Module', @INC);
82 Like new_from_module(), except all modules in @INC will be
84 returned, in the order they are found. Thus $modules[0] is the one
85 that would be loaded by "use Some::Module".
86 Information without loading
88 The following methods get their information without actually compiling
90 the module.
91 name
93 my $name = $module->name;
94 $module->name($name);
95 Name of the module (ie. Some::Module).
97 Module loaded using new_from_file() won't have this information in
99 which case you can set it yourself.
100 version
102 my $version = $module->version;
103 Divines the value of $VERSION. This uses the same method as ExtU‐
105 tils::MakeMaker and all caveats therein apply.
106 inc_dir
108 my $dir = $module->inc_dir;
109 Include directory in which this module was found. Module::Info
111 objects created with new_from_file() won't have this info.
112 file
114 my $file = $module->file;
115 The absolute path to this module.
117 is_core
119 my $is_core = $module->is_core;
120 Checks if this module is the one distributed with Perl.
122 NOTE This goes by what directory it's in. It's possible that the
124 module has been altered or upgraded from CPAN since the original
125 Perl installation.
126 Information that requires loading.
128 WARNING! From here down reliability drops rapidly!
130 The following methods get their information by compiling the module and
132 examining the opcode tree. The module will be compiled in a seperate
133 process so as not to disturb the current program.
134 They will only work on 5.6.1 and up and requires the B::Utils module.
136 packages_inside
138 my @packages = $module->packages_inside;
139 Looks for any explicit "package" declarations inside the module and
141 returns a list. Useful for finding hidden classes and functional‐
142 ity (like Tie::StdHandle inside Tie::Handle).
143 KNOWN BUG Currently doesn't spot package changes inside subrou‐
145 tines.
146 package_versions
148 my %versions = $module->package_versions;
149 Returns a hash whose keys are the packages contained in the module
151 (these are the same as what's returned by "packages_inside()"), and
152 whose values are the versions of those packages.
153 modules_used
155 my @used = $module->modules_used;
156 Returns a list of all modules and files which may be "use"'d or
158 "require"'d by this module.
159 NOTE These modules may be conditionally loaded, can't tell. Also
161 can't find modules which might be used inside an "eval".
162 modules_required
164 my %required = $module->modules_required;
165 Returns a list of all modules and files which may be "use"'d or
167 "require"'d by this module, together with the minimum required ver‐
168 sion.
169 The hash is keyed on the module/file name, the corrisponding value
171 is an array reference containing the requied versions, or an empty
172 array if no specific version was required.
173 NOTE These modules may be conditionally loaded, can't tell. Also
175 can't find modules which might be used inside an "eval".
176 subroutines
178 my %subs = $module->subroutines;
179 Returns a hash of all subroutines defined inside this module and
181 some info about it. The key is the *full* name of the subroutine
182 (ie. $subs{'Some::Module::foo'} rather than just $subs{'foo'}),
183 value is a hash ref with information about the subroutine like so:
184 start => line number of the first statement in the subroutine
186 end => line number of the last statement in the subroutine
187 Note that the line numbers may not be entirely accurate and will
189 change as perl's backend compiler improves. They typically corre‐
190 spond to the first and last run-time statements in a subroutine.
191 For example:
192 sub foo {
194 package Wibble;
195 $foo = "bar";
196 return $foo;
197 }
198 Taking "sub foo {" as line 1, Module::Info will report line 3 as
200 the start and line 4 as the end. "package Wibble;" is a compile-
201 time statement. Again, this will change as perl changes.
202 Note this only catches simple "sub foo {...}" subroutine declara‐
204 tions. Anonymous, autoloaded or eval'd subroutines are not listed.
205 superclasses
207 my @isa = $module->superclasses;
208 Returns the value of @ISA for this $module. Requires that $mod‐
210 ule->name be set to work.
211 NOTE superclasses() is currently cheating. See CAVEATS below.
213 subroutines_called
215 my @calls = $module->subroutines_called;
216 Finds all the methods and functions which are called inside the
218 $module.
219 Returns a list of hashes. Each hash represents a single function
221 or method call and has the keys:
222 line line number where this call originated
224 class class called on if its a class method
225 type function, symbolic function, object method,
226 class method, dynamic object method or
227 dynamic class method.
228 (NOTE This format will probably change)
229 name name of the function/method called if not dynamic
230 Information about Unpredictable Constructs
232 Unpredictable constructs are things that make a Perl program hard to
234 predict what its going to do without actually running it. There's
235 nothing wrong with these constructs, but its nice to know where they
236 are when maintaining a piece of code.
237 dynamic_method_calls
239 my @methods = $module->dynamic_method_calls;
240 Returns a list of dynamic method calls (ie. "$obj-"$method()>) used
242 by the $module. @methods has the same format as the return value
243 of subroutines_called().
244 Options
246 The following methods get/set specific option values for the Mod‐
248 ule::Info object.
249 die_on_compilation_error
251 $module->die_on_compilation_error(0); # default
252 $module->die_on_compilation_error(1);
253 my $flag = $module->die_on_compilation_error;
254 Sets/gets the "die on compilation error" flag. When the flag is off
256 (default), and a module fails to compile, Module::Info simply emits
257 a watning and continues. When the flag is on and a module fails to
258 compile, Module::Info "die()"s with the same error message it would
259 use in the warning.
260 safe
262 $module->safe(0); # default
263 $module->safe(1); # be safer
264 my $flag = $module->safe;
265 Sets/gets the "safe" flag. When the flag is enabled all operations
267 requiring module compilation are forbidden and the "version()"
268 method executes its code in a "Safe" compartment.
269 use_version
271 $module->use_version(0); # do not use version.pm (default)
272 $module->use_version(1); # use version.pm, die if not present
273 my $flag = $module->use_version;
274 Sets/gets the "use_version" flag. When the flag is enabled the
276 'version' method always returns a version object.
277
279 Michael G Schwern <schwern@pobox.com> with code from ExtUtils::MM_Unix,
280 Module::InstalledVersion and lots of cargo-culting from B::Deparse.
281 Mattia Barbon <mbarbon@cpan.org> is the current maintainer.
283
285 This program is free software; you can redistribute it and/or modify it
286 under the same terms as Perl itself.
287
289 Many thanks to Simon Cozens and Robin Houston for letting me chew their
290 ears about B.
291
293 Code refs in @INC are currently ignored. If this bothers you submit a
294 patch.
295 superclasses() is cheating and just loading the module in a seperate
297 process and looking at @ISA. I don't think its worth the trouble to go
298 through and parse the opcode tree as it still requires loading the mod‐
299 ule and running all the BEGIN blocks. Patches welcome.
300 I originally was going to call superclasses() isa() but then I remem‐
302 bered that would be bad.
303 All the methods that require loading are really inefficient as they're
305 not caching anything. I'll worry about efficiency later.
306perl v5.8.8 2007-04-18 Module::Info(3)