NAME¶
Module::Info - Information about Perl modules
SYNOPSIS¶
use Module::Info;
my $mod = Module::Info->new_from_file('Some/Module.pm');
my $mod = Module::Info->new_from_module('Some::Module');
my $mod = Module::Info->new_from_loaded('Some::Module');
my @mods = Module::Info->all_installed('Some::Module');
my $name = $mod->name;
my $version = $mod->version;
my $dir = $mod->inc_dir;
my $file = $mod->file;
my $is_core = $mod->is_core;
# Only available in perl 5.6.1 and up.
# These do compile the module.
my @packages = $mod->packages_inside;
my @used = $mod->modules_used;
my @subs = $mod->subroutines;
my @isa = $mod->superclasses;
my @calls = $mod->subroutines_called;
# Check for constructs which make perl hard to predict.
my @methods = $mod->dynamic_method_calls;
my @lines = $mod->eval_string; *UNIMPLEMENTED*
my @lines = $mod->gotos; *UNIMPLEMENTED*
my @controls = $mod->exit_via_loop_control; *UNIMPLEMENTED*
my @unpredictables = $mod->has_unpredictables; *UNIMPLEMENTED*
# set/get Module::Info options
$self->die_on_compilation_error(1);
my $die_on_error = $mod->die_on_compilation_error;
$self->safe(1);
my $safe = $mod->safe;
DESCRIPTION¶
Module::Info gives you information about Perl modules
without actually
loading the module. It actually isn't specific to modules and should work
on any perl code.
METHODS¶
Constructors¶
There are a few ways to specify which module you want information for. They all
return Module::Info objects.
- new_from_file
-
my $module = Module::Info->new_from_file('path/to/Some/Module.pm');
Given a file, it will interpret this as the module you want information
about. You can also hand it a perl script.
If the file doesn't exist or isn't readable it will return false.
- new_from_module
-
my $module = Module::Info->new_from_module('Some::Module');
my $module = Module::Info->new_from_module('Some::Module', @INC);
Given a module name, @INC will be searched and the first module found used.
This is the same module that would be loaded if you just say "use
Some::Module".
If you give your own @INC, that will be used to search instead.
- new_from_loaded
-
my $module = Module::Info->new_from_loaded('Some::Module');
Gets information about the currently loaded version of Some::Module. If it
isn't loaded, returns false.
- all_installed
-
my @modules = Module::Info->all_installed('Some::Module');
my @modules = Module::Info->all_installed('Some::Module', @INC);
Like new_from_module(), except all modules in @INC will be
returned, in the order they are found. Thus $modules[0] is the one that
would be loaded by "use Some::Module".
The following methods get their information without actually compiling the
module.
- name
-
my $name = $module->name;
$module->name($name);
Name of the module (ie. Some::Module).
Module loaded using new_from_file() won't have this information in
which case you can set it yourself.
- version
-
my $version = $module->version;
Divines the value of $VERSION. This uses the same method as
ExtUtils::MakeMaker and all caveats therein apply.
- inc_dir
-
my $dir = $module->inc_dir;
Include directory in which this module was found. Module::Info objects
created with new_from_file() won't have this info.
- file
-
my $file = $module->file;
The absolute path to this module.
- is_core
-
my $is_core = $module->is_core;
Checks if this module is the one distributed with Perl.
NOTE This goes by what directory it's in. It's possible that the
module has been altered or upgraded from CPAN since the original Perl
installation.
WARNING! From here down reliability drops rapidly!
The following methods get their information by compiling the module and
examining the opcode tree. The module will be compiled in a separate process
so as not to disturb the current program.
They will only work on 5.6.1 and up and requires the B::Utils module.
- packages_inside
-
my @packages = $module->packages_inside;
Looks for any explicit "package" declarations inside the module
and returns a list. Useful for finding hidden classes and functionality
(like Tie::StdHandle inside Tie::Handle).
KNOWN BUG Currently doesn't spot package changes inside
subroutines.
- package_versions
-
my %versions = $module->package_versions;
Returns a hash whose keys are the packages contained in the module (these
are the same as what's returned by "packages_inside()"), and
whose values are the versions of those packages.
- modules_used
-
my @used = $module->modules_used;
Returns a list of all modules and files which may be "use"'d or
"require"'d by this module.
NOTE These modules may be conditionally loaded, can't tell. Also
can't find modules which might be used inside an "eval".
- modules_required
-
my %required = $module->modules_required;
Returns a list of all modules and files which may be "use"'d or
"require"'d by this module, together with the minimum required
version.
The hash is keyed on the module/file name, the corrisponding value is an
array reference containing the requied versions, or an empty array if no
specific version was required.
NOTE These modules may be conditionally loaded, can't tell. Also
can't find modules which might be used inside an "eval".
- subroutines
-
my %subs = $module->subroutines;
Returns a hash of all subroutines defined inside this module and some info
about it. The key is the *full* name of the subroutine (ie.
$subs{'Some::Module::foo'} rather than just $subs{'foo'}), value is a hash
ref with information about the subroutine like so:
start => line number of the first statement in the subroutine
end => line number of the last statement in the subroutine
Note that the line numbers may not be entirely accurate and will change as
perl's backend compiler improves. They typically correspond to the first
and last run-time statements in a subroutine. For example:
sub foo {
package Wibble;
$foo = "bar";
return $foo;
}
Taking "sub foo {" as line 1, Module::Info will report line 3 as
the start and line 4 as the end. "package Wibble;" is a
compile-time statement. Again, this will change as perl changes.
Note this only catches simple "sub foo {...}" subroutine
declarations. Anonymous, autoloaded or eval'd subroutines are not
listed.
- superclasses
-
my @isa = $module->superclasses;
Returns the value of @ISA for this $module. Requires that $module->name
be set to work.
NOTE superclasses() is currently cheating. See CAVEATS
below.
- subroutines_called
-
my @calls = $module->subroutines_called;
Finds all the methods and functions which are called inside the $module.
Returns a list of hashes. Each hash represents a single function or method
call and has the keys:
line line number where this call originated
class class called on if its a class method
type function, symbolic function, object method,
class method, dynamic object method or
dynamic class method.
(NOTE This format will probably change)
name name of the function/method called if not dynamic
Unpredictable constructs are things that make a Perl program hard to predict
what its going to do without actually running it. There's nothing wrong with
these constructs, but its nice to know where they are when maintaining a piece
of code.
- dynamic_method_calls
-
my @methods = $module->dynamic_method_calls;
Returns a list of dynamic method calls (ie. "$obj-"$
method()>) used by the $module. @methods has the same format as
the return value of subroutines_called().
Options¶
The following methods get/set specific option values for the Module::Info
object.
- die_on_compilation_error
-
$module->die_on_compilation_error(0); # default
$module->die_on_compilation_error(1);
my $flag = $module->die_on_compilation_error;
Sets/gets the "die on compilation error" flag. When the flag is
off (default), and a module fails to compile, Module::Info simply emits a
watning and continues. When the flag is on and a module fails to compile,
Module::Info "die()"s with the same error message it would use
in the warning.
- safe
-
$module->safe(0); # default
$module->safe(1); # be safer
my $flag = $module->safe;
Sets/gets the "safe" flag. When the flag is enabled all operations
requiring module compilation are forbidden and the "version()"
method executes its code in a "Safe" compartment.
- use_version
-
$module->use_version(0); # do not use version.pm (default)
$module->use_version(1); # use version.pm, die if not present
my $flag = $module->use_version;
Sets/gets the "use_version" flag. When the flag is enabled the
'version' method always returns a version object.
AUTHOR¶
Michael G Schwern <schwern@pobox.com> with code from ExtUtils::MM_Unix,
Module::InstalledVersion and lots of cargo-culting from B::Deparse.
Mattia Barbon <mbarbon@cpan.org> is the current maintainer.
LICENSE¶
This program is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.
THANKS¶
Many thanks to Simon Cozens and Robin Houston for letting me chew their ears
about B.
CAVEATS¶
Code refs in @INC are currently ignored. If this bothers you submit a patch.
superclasses() is cheating and just loading the module in a separate
process and looking at @ISA. I don't think its worth the trouble to go through
and parse the opcode tree as it still requires loading the module and running
all the BEGIN blocks. Patches welcome.
I originally was going to call
superclasses() isa() but then I
remembered that would be bad.
All the methods that require loading are really inefficient as they're not
caching anything. I'll worry about efficiency later.