Module::Load::Conditional(3pm)

1Module::Load::ConditionUasle(r3)Contributed Perl DocumenMtoadtuiloen::Load::Conditional(3)
2
3
4

NAME

6       Module::Load::Conditional - Looking up module information / loading at
7       runtime
8

SYNOPSIS

10           use Module::Load::Conditional qw[can_load check_install requires];
11
12           my $use_list = {
13                   CPANPLUS        => 0.05,
14                   LWP             => 5.60,
15                   'Test::More'    => undef,
16           };
17
18           print can_load( modules => $use_list )
19                   ? 'all modules loaded successfully'
20                   : 'failed to load required modules';
21
22           my $rv = check_install( module => 'LWP', version => 5.60 )
23                       or print 'LWP is not installed!';
24
25           print 'LWP up to date' if $rv->{uptodate};
26           print "LWP version is $rv->{version}\n";
27           print "LWP is installed as file $rv->{file}\n";
28
29           print "LWP requires the following modules to be installed:\n";
30           print join "\n", requires('LWP');
31
32           ### allow M::L::C to peek in your %INC rather than just
33           ### scanning @INC
34           $Module::Load::Conditional::CHECK_INC_HASH = 1;
35
36           ### reset the 'can_load' cache
37           undef $Module::Load::Conditional::CACHE;
38
39           ### don't have Module::Load::Conditional issue warnings --
40           ### default is '1'
41           $Module::Load::Conditional::VERBOSE = 0;
42
43           ### The last error that happened during a call to 'can_load'
44           my $err = $Module::Load::Conditional::ERROR;
45

DESCRIPTION

47       Module::Load::Conditional provides simple ways to query and possibly
48       load any of the modules you have installed on your system during run‐
49       time.
50
51       It is able to load multiple modules at once or none at all if one of
52       them was not able to load. It also takes care of any error checking and
53       so forth.
54

Methods

$href = check_install( module => NAME [, version => VERSION, verbose => BOOL ]

57       );
58       "check_install" allows you to verify if a certain module is installed
59       or not. You may call it with the following arguments:
60
61       module
62           The name of the module you wish to verify -- this is a required key
63
64       version
65           The version this module needs to be -- this is optional
66
67       verbose
68           Whether or not to be verbose about what it is doing -- it will
69           default to $Module::Load::Conditional::VERBOSE
70
71       It will return undef if it was not able to find where the module was
72       installed, or a hash reference with the following keys if it was able
73       to find the file:
74
75       file
76           Full path to the file that contains the module
77
78       version
79           The version number of the installed module - this will be "undef"
80           if the module had no (or unparsable) version number, or if the
81           variable $Module::Load::Conditional::FIND_VERSION was set to true.
82           (See the "GLOBAL VARIABLES" section below for details)
83
84       uptodate
85           A boolean value indicating whether or not the module was found to
86           be at least the version you specified. If you did not specify a
87           version, uptodate will always be true if the module was found.  If
88           no parsable version was found in the module, uptodate will also be
89           true, since "check_install" had no way to verify clearly.
90
91       $bool = can_load( modules => { NAME => VERSION [,NAME => VERSION] },
92       [verbose => BOOL, nocache => BOOL] )
93
94       "can_load" will take a list of modules, optionally with version numbers
95       and determine if it is able to load them. If it can load *ALL* of them,
96       it will. If one or more are unloadable, none will be loaded.
97
98       This is particularly useful if you have More Than One Way (tm) to solve
99       a problem in a program, and only wish to continue down a path if all
100       modules could be loaded, and not load them if they couldn't.
101
102       This function uses the "load" function from Module::Load under the
103       hood.
104
105       "can_load" takes the following arguments:
106
107       modules
108           This is a hashref of module/version pairs. The version indicates
109           the minimum version to load. If no version is provided, any version
110           is assumed to be good enough.
111
112       verbose
113           This controls whether warnings should be printed if a module failed
114           to load.  The default is to use the value of $Module::Load::Condi‐
115           tional::VERBOSE.
116
117       nocache
118           "can_load" keeps its results in a cache, so it will not load the
119           same module twice, nor will it attempt to load a module that has
120           already failed to load before. By default, "can_load" will check
121           its cache, but you can override that by setting "nocache" to true.
122
123       @list = requires( MODULE );
124
125       "requires" can tell you what other modules a particular module
126       requires. This is particularly useful when you're intending to write a
127       module for public release and are listing its prerequisites.
128
129       "requires" takes but one argument: the name of a module.  It will then
130       first check if it can actually load this module, and return undef if it
131       can't.  Otherwise, it will return a list of modules and pragmas that
132       would have been loaded on the module's behalf.
133
134       Note: The list "require" returns has originated from your current perl
135       and your current install.
136

Global Variables

138       The behaviour of Module::Load::Conditional can be altered by changing
139       the following global variables:
140
141       $Module::Load::Conditional::VERBOSE
142
143       This controls whether Module::Load::Conditional will issue warnings and
144       explanations as to why certain things may have failed. If you set it to
145       0, Module::Load::Conditional will not output any warnings.  The default
146       is 0;
147
148       $Module::Load::Conditional::FIND_VERSION
149
150       This controls whether Module::Load::Conditional will try to parse (and
151       eval) the version from the module you're trying to load.
152
153       If you don't wish to do this, set this variable to "false". Understand
154       then that version comparisons are not possible, and Module::Load::Con‐
155       ditional can not tell you what module version you have installed.  This
156       may be desirable from a security or performance point of view.  Note
157       that $FIND_VERSION code runs safely under "taint mode".
158
159       The default is 1;
160
161       $Module::Load::Conditional::CHECK_INC_HASH
162
163       This controls whether "Module::Load::Conditional" checks your %INC hash
164       to see if a module is available. By default, only @INC is scanned to
165       see if a module is physically on your filesystem, or avialable via an
166       "@INC-hook". Setting this variable to "true" will trust any entries in
167       %INC and return them for you.
168
169       The default is 0;
170
171       $Module::Load::Conditional::CACHE
172
173       This holds the cache of the "can_load" function. If you explicitly want
174       to remove the current cache, you can set this variable to "undef"
175
176       $Module::Load::Conditional::ERROR
177
178       This holds a string of the last error that happened during a call to
179       "can_load". It is useful to inspect this when "can_load" returns
180       "undef".
181

AUTHOR

186       This module by Jos Boumans <kane@cpan.org>.
187

COPYRIGHT

189       This module is copyright (c) 2002-2007 Jos Boumans <kane@cpan.org>. All
190       rights reserved.
191
192       This library is free software; you may redistribute and/or modify it
193       under the same terms as Perl itself.
194
195
196
197perl v5.8.8                       2007-01-25      Module::Load::Conditional(3)