Unix/Linux Go Back    


SuSE 11.3 - man page for module::info (suse section 3)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


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

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

perl v5.12.1				    2007-05-28				  Module::Info(3)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 10:33 AM.