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

FreeBSD Manual Pages

  
 
  

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

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

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

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

   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.

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

NAME | SYNOPSIS | DESCRIPTION | METHODS | AUTHOR | LICENSE | THANKS | CAVEATS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Module::Info&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help