GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  MODULE::INFO (3)

.ds Aq ’

NAME

Module::Info - Information about Perl modules

CONTENTS

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 <B>without actually loading the moduleB>. 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.
<B>nameB>


  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.

<B>versionB>


  my $version = $module->version;



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

<B>inc_dirB>


  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.

<B>fileB>


  my $file = $module->file;



The absolute path to this module.

<B>is_coreB>


  my $is_core = $module->is_core;



Checks if this module is the one distributed with Perl.

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

<B>WARNING!B> 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.
<B>packages_insideB>


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

<B>KNOWN BUGB> Currently doesn’t spot package changes inside subroutines.

<B>package_versionsB>


  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.

<B>modules_usedB>


  my @used = $module->modules_used;



Returns a list of all modules and files which may be use’d or require’d by this module.

<B>NOTEB> These modules may be conditionally loaded, can’t tell. Also can’t find modules which might be used inside an eval.

<B>modules_requiredB>


  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.

<B>NOTEB> These modules may be conditionally loaded, can’t tell. Also can’t find modules which might be used inside an eval.

<B>subroutinesB>


  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.

<B>superclassesB>


  my @isa = $module->superclasses;



Returns the value of @ISA for this $module. Requires that $module->name be set to work.

<B>NOTEB> superclasses() is currently cheating. See CAVEATS below.

<B>subroutines_calledB>


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


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


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

<B>safeB>


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

<B>use_versionB>


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

Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 MODULE::INFO (3) 2013-09-08

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.