CPANPLUS::Tools::Module - Looking up module information / loading at runtime
use CPANPLUS::Tools::Module qw[can_use check_install requires]; my $use_list = { CPANPLUS => 0.05, LWP => 5.60, 'Test::More' => undef, }; print can_load( modules => $use_list ) ? 'all modules loaded succesfully' : 'failed to load required modules'; my $rv = check_install( module => 'LWP', verion => 5.60 ) or print 'LWP is not installed!'; print 'LWP up to date' if $rv->{uptodate}; print "LWP version is $rv->{version}\n"; print "LWP is installed as file $rv->{file}\n"; print "LWP requires the following modules to be installed:\n"; print join "\n", requires('LWP'); ### reset the 'can_load' cache undef $CPANPLUS::Tools::Module::CACHE; ### don't have CPANPLUS::Tools::Module issue warnings -- default is '1' $CPANPLUS::Tools::Module::VERBOSE = 0; ### The last error that happened during a call to 'can_load' my $err = $CPANPLUS::Tools::Module::ERROR;
CPANPLUS::Tools::Module provides simple ways to query and possibly load any of the modules you have installed on your system during runtime.
It is able to load multiple modules at once or none at all if one of them was not able to load. It also takes care of any error checking and so forth.
check_install allows you to verify if a certain module is installed or not. You may call it with the following arguments:
check_install
The name of the module you wish to verify -- this is a required key
The version this module needs to be -- this is optional
Whether or not to be verbose about what it is doing -- it will default to $CPANPLUS::Tools::Module::VERBOSE
It will return undef if it was not able to find where the module was installed, or a hash reference with the following keys if it was able to find the file:
Full path to the file that contains the module
The version number of the installed module - this will be undef if the module had no or an unparsable version number.
undef
A boolean value indicating whether or not the module was found to be at least the version you specified. If you did not specify a version, uptodate will always be true if the module was found. If no parsable version was found in the module, uptodate will also be true, since check_install had no way to verify clearly.
can_load will take a list of modules, optionally with version numbers and determine if it is able to load them. If it can load *ALL* of them, it will. If one or more are unloadable, none will be loaded.
can_load
This is particularly usefull if you have More Than One Way (tm) to solve a problem in a program, and only wish to continue down a path if all modules could be loaded, and not load them if they couldn't.
This function uses the load function from CPANPLUS::Tools::Load under the hood.
load
can_load takes the following arguments:
This is a hashref of module/version pairs. The version indicates the minimum version to load. If no version is provided, any version is assumed to be good enough.
This controls whether warnings should be printed if a module failed to load. A synonym is complain. The default is to use the value of $CPANPLUS::Tools::Module::VERBOSE.
complain
can_load keeps it's results in a cache, so it will not load the same module twice, nor will it attempt to load a module that has already failed to load before. By default, can_load will check it's cache, but you can override that by setting nocache to true.
nocache
requires can tell you what other modules a particular module requires. This is particularly usefull when you're intending to write a module for public release and are listing it's prerequisites.
requires
requires takes but one argument: the name of a module. It will then first check if it can actually load this module, and return undef if it can't. Otherwise, it will return a list of modules and pragma's that would have been loaded on the module's behalf.
Note: The list require returns has originated from your current perl and your current install.
require
The behaviour of CPANPLUS::Tools::Module can be altered by changing the following global variables:
This controls whether CPANPLUS::Tools::Module will issue warnings and explenations as to why certain things may have failed. If you set it to 0, CPANPLUS::Tools::Module will not output any warnings. The default is 1;
This holds the cache of the can_load function. If you explicitly want to remove the current cache, you can set this variable to undef
This holds a string of the last error that happened during a call to can_load. It is useful to inspect this when can_load returns undef.
CPANPLUS::Tools::Load
This module by Jos Boumans <kane@cpan.org>.
This module is copyright (c) 2002 Jos Boumans <kane@cpan.org>. All rights reserved.
This library is free software; you may redistribute and/or modify it under the same terms as Perl itself.
1 POD Error
The following errors were encountered while parsing the POD:
You forgot a '=back' before '=head2'
To install CPANPLUS, copy and paste the appropriate command in to your terminal.
cpanm
cpanm CPANPLUS
CPAN shell
perl -MCPAN -e shell install CPANPLUS
For more information on module installation, please visit the detailed CPAN module installation guide.