http://www.pobox.com/~schwern/src/Module-Info-0.12.tar.gz
Added pfunc into the dist and fixed some bugs found while writing that.
0.12 Sat Feb 2 19:41:01 EST 2002
* Added pfunc
- Now tested back to 5.004
* Fixed a bug where certain modules were being ignored
- Fixed a bug in subroutines_called() with EXPR->method()
- subroutines_called() now reports properly on function calls
with symbolic refs
0.11 Sat Feb 2 16:54:23 EST 2002
* Fixed B::Utils->kids
* Added subroutines_called()
* Added superclasses()
* Added dynamic_method_calls()
- Documented that it isn't just for modules.
- name() can now be used to set
- failures inside B::Module::Info now report their errors instead of
failing silently
* Added a THANKS section.
NAME
pfunc - grep for perl functions
SYNOPSIS
pfunc subroutine FILES...
DESCRIPTION
pfunc searches the named FILES for all calls to the given subroutine. It
will report back the file and line number each call is found on along
with what sort of call it is
function foo()
class method Class->foo()
object method $obj->foo()
EXAMPLE
$ pfunc isa /usr/share/perl/5.6.1/*.pm
Called as function in /usr/share/perl/5.6.1/CGI.pm at line 316
Called as function in /usr/share/perl/5.6.1/CGI.pm at line 327
Called as function in /usr/share/perl/5.6.1/CGI.pm at line 397
Called as function in /usr/share/perl/5.6.1/CGI.pm at line 494
Called as function in /usr/share/perl/5.6.1/CGI.pm at line 495
Called as object method in /usr/share/perl/5.6.1/CPAN.pm at line 4957
Called as function in /usr/share/perl/5.6.1/Dumpvalue.pm at line 191
Called as function in /usr/share/perl/5.6.1/Dumpvalue.pm at line 218
Called as function in /usr/share/perl/5.6.1/Dumpvalue.pm at line 248
Called as function in /usr/share/perl/5.6.1/Dumpvalue.pm at line 251
Called as function in /usr/share/perl/5.6.1/Dumpvalue.pm at line 254
Called as object method in /usr/share/perl/5.6.1/Shell.pm at line 28
Called as object method in /usr/share/perl/5.6.1/base.pm at line 12
NOTES
Its not fast, but its accurate.
AUTHOR
Michael G Schwern <[EMAIL PROTECTED]>
SEE ALSO
Module::Info
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*
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".
Information without loading
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.
Information that requires loading.
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 seperate
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.
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".
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
Information about Unpredictable Constructs
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().
AUTHOR
Michael G Schwern <[EMAIL PROTECTED]> with code from ExtUtils::MM_Unix,
Module::InstalledVersion and lots of cargo-culting from B::Deparse.
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 seperate
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.
--
Michael G. Schwern <[EMAIL PROTECTED]> http://www.pobox.com/~schwern/
Perl Quality Assurance <[EMAIL PROTECTED]> Kwalitee Is Job One
Beef Coronary
