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 Information that requires loading.
126 WARNING! From here down reliability drops rapidly!
127 The following methods get their information by compiling the module and
129 examining the opcode tree. The module will be compiled in a seperate
130 process so as not to disturb the current program.
131 They will only work on 5.6.1 and up and requires the B::Utils module.
133 packages_inside
135 my @packages = $module->packages_inside;
136 Looks for any explicit "package" declarations inside the module and
138 returns a list. Useful for finding hidden classes and
139 functionality (like Tie::StdHandle inside Tie::Handle).
140 KNOWN BUG Currently doesn't spot package changes inside
142 subroutines.
143 package_versions
145 my %versions = $module->package_versions;
146 Returns a hash whose keys are the packages contained in the module
148 (these are the same as what's returned by "packages_inside()"), and
149 whose values are the versions of those packages.
150 modules_used
152 my @used = $module->modules_used;
153 Returns a list of all modules and files which may be "use"'d or
155 "require"'d by this module.
156 NOTE These modules may be conditionally loaded, can't tell. Also
158 can't find modules which might be used inside an "eval".
159 modules_required
161 my %required = $module->modules_required;
162 Returns a list of all modules and files which may be "use"'d or
164 "require"'d by this module, together with the minimum required
165 version.
166 The hash is keyed on the module/file name, the corrisponding value
168 is an array reference containing the requied versions, or an empty
169 array if no specific version was required.
170 NOTE These modules may be conditionally loaded, can't tell. Also
172 can't find modules which might be used inside an "eval".
173 subroutines
175 my %subs = $module->subroutines;
176 Returns a hash of all subroutines defined inside this module and
178 some info about it. The key is the *full* name of the subroutine
179 (ie. $subs{'Some::Module::foo'} rather than just $subs{'foo'}),
180 value is a hash ref with information about the subroutine like so:
181 start => line number of the first statement in the subroutine
183 end => line number of the last statement in the subroutine
184 Note that the line numbers may not be entirely accurate and will
186 change as perl's backend compiler improves. They typically
187 correspond to the first and last run-time statements in a
188 subroutine. For example:
189 sub foo {
191 package Wibble;
192 $foo = "bar";
193 return $foo;
194 }
195 Taking "sub foo {" as line 1, Module::Info will report line 3 as
197 the start and line 4 as the end. "package Wibble;" is a compile-
198 time statement. Again, this will change as perl changes.
199 Note this only catches simple "sub foo {...}" subroutine
201 declarations. Anonymous, autoloaded or eval'd subroutines are not
202 listed.
203 superclasses
205 my @isa = $module->superclasses;
206 Returns the value of @ISA for this $module. Requires that
208 $module->name be set to work.
209 NOTE superclasses() is currently cheating. See CAVEATS below.
211 subroutines_called
213 my @calls = $module->subroutines_called;
214 Finds all the methods and functions which are called inside the
216 $module.
217 Returns a list of hashes. Each hash represents a single function
219 or method call and has the keys:
220 line line number where this call originated
222 class class called on if its a class method
223 type function, symbolic function, object method,
224 class method, dynamic object method or
225 dynamic class method.
226 (NOTE This format will probably change)
227 name name of the function/method called if not dynamic
228 Information about Unpredictable Constructs
230 Unpredictable constructs are things that make a Perl program hard to
231 predict what its going to do without actually running it. There's
232 nothing wrong with these constructs, but its nice to know where they
233 are when maintaining a piece of code.
234 dynamic_method_calls
236 my @methods = $module->dynamic_method_calls;
237 Returns a list of dynamic method calls (ie. "$obj-"$method()>) used
239 by the $module. @methods has the same format as the return value
240 of subroutines_called().
241 Options
243 The following methods get/set specific option values for the
244 Module::Info object.
245 die_on_compilation_error
247 $module->die_on_compilation_error(0); # default
248 $module->die_on_compilation_error(1);
249 my $flag = $module->die_on_compilation_error;
250 Sets/gets the "die on compilation error" flag. When the flag is off
252 (default), and a module fails to compile, Module::Info simply emits
253 a watning and continues. When the flag is on and a module fails to
254 compile, Module::Info "die()"s with the same error message it would
255 use in the warning.
256 safe
258 $module->safe(0); # default
259 $module->safe(1); # be safer
260 my $flag = $module->safe;
261 Sets/gets the "safe" flag. When the flag is enabled all operations
263 requiring module compilation are forbidden and the "version()"
264 method executes its code in a "Safe" compartment.
265 use_version
267 $module->use_version(0); # do not use version.pm (default)
268 $module->use_version(1); # use version.pm, die if not present
269 my $flag = $module->use_version;
270 Sets/gets the "use_version" flag. When the flag is enabled the
272 'version' method always returns a version object.
273
275 Michael G Schwern <schwern@pobox.com> with code from ExtUtils::MM_Unix,
276 Module::InstalledVersion and lots of cargo-culting from B::Deparse.
277 Mattia Barbon <mbarbon@cpan.org> is the current maintainer.
279
281 This program is free software; you can redistribute it and/or modify it
282 under the same terms as Perl itself.
283
285 Many thanks to Simon Cozens and Robin Houston for letting me chew their
286 ears about B.
287
289 Code refs in @INC are currently ignored. If this bothers you submit a
290 patch.
291 superclasses() is cheating and just loading the module in a seperate
293 process and looking at @ISA. I don't think its worth the trouble to go
294 through and parse the opcode tree as it still requires loading the
295 module and running all the BEGIN blocks. Patches welcome.
296 I originally was going to call superclasses() isa() but then I
298 remembered that would be bad.
299 All the methods that require loading are really inefficient as they're
301 not caching anything. I'll worry about efficiency later.
302perl v5.10.1 2010-11-12 Module::Info(3)