Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
Module::Info(3)	      User Contributed Perl Documentation      Module::Info(3)

       Module::Info - Information about	Perl modules

	 use Module::Info;

	 my $mod = Module::Info->new_from_file('Some/');
	 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
	 my $die_on_error = $mod->die_on_compilation_error;
	 my $safe = $mod->safe;

       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.

       There are a few ways to specify which module you	want information for.
       They all	return Module::Info objects.

	     my	$module	= Module::Info->new_from_file('path/to/Some/');

	   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.

	     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.

	     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.

	     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.

	     my	$name =	$module->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.

	     my	$version = $module->version;

	   Divines the value of	$VERSION.  This	uses the same method as
	   ExtUtils::MakeMaker and all caveats therein apply.

	     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.

	     my	$file =	$module->file;

	   The absolute	path to	this module.

	     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 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.

	     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

	     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.

	     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".

	     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

	   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".

	     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

	     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.

	     my	@calls = $module->subroutines_called;

	   Finds all the methods and functions which are called	inside the

	   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.

	     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().

       The following methods get/set specific option values for	the
       Module::Info object.

	     $module->die_on_compilation_error(0); # default
	     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.

	     $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.

	     $module->use_version(0); #	do not use (default)
	     $module->use_version(1); #	use,	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.

       Michael G Schwern <> with code from ExtUtils::MM_Unix,
       Module::InstalledVersion	and lots of cargo-culting from B::Deparse.

       Mattia Barbon <>	is the current maintainer.

       This program is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself.

       Many thanks to Simon Cozens and Robin Houston for letting me chew their
       ears about B.

       Code refs in @INC are currently ignored.	 If this bothers you submit a

       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.

perl v5.32.1			  2013-09-08		       Module::Info(3)


Want to link to this manual page? Use this URL:

home | help