1Module::Load::ConditionaPle(r3lpmP)rogrammers ReferenceMoGduuildee::Load::Conditional(3pm)
2
6 Module::Load::Conditional - Looking up module information / loading at
7 runtime
8
10 use Module::Load::Conditional qw[can_load check_install requires];
11 my $use_list = {
14 CPANPLUS => 0.05,
15 LWP => 5.60,
16 'Test::More' => undef,
17 };
18 print can_load( modules => $use_list )
20 ? 'all modules loaded successfully'
21 : 'failed to load required modules';
22 my $rv = check_install( module => 'LWP', version => 5.60 )
25 or print 'LWP is not installed!';
26 print 'LWP up to date' if $rv->{uptodate};
28 print "LWP version is $rv->{version}\n";
29 print "LWP is installed as file $rv->{file}\n";
30 print "LWP requires the following modules to be installed:\n";
33 print join "\n", requires('LWP');
34 ### allow M::L::C to peek in your %INC rather than just
36 ### scanning @INC
37 $Module::Load::Conditional::CHECK_INC_HASH = 1;
38 ### reset the 'can_load' cache
40 undef $Module::Load::Conditional::CACHE;
41 ### don't have Module::Load::Conditional issue warnings --
43 ### default is '1'
44 $Module::Load::Conditional::VERBOSE = 0;
45 ### The last error that happened during a call to 'can_load'
47 my $err = $Module::Load::Conditional::ERROR;
48
50 Module::Load::Conditional provides simple ways to query and possibly
51 load any of the modules you have installed on your system during
52 runtime.
53 It is able to load multiple modules at once or none at all if one of
55 them was not able to load. It also takes care of any error checking and
56 so forth.
57
60 );
61 "check_install" allows you to verify if a certain module is installed
62 or not. You may call it with the following arguments:
63 module
65 The name of the module you wish to verify -- this is a required key
66 version
68 The version this module needs to be -- this is optional
69 verbose
71 Whether or not to be verbose about what it is doing -- it will
72 default to $Module::Load::Conditional::VERBOSE
73 It will return undef if it was not able to find where the module was
75 installed, or a hash reference with the following keys if it was able
76 to find the file:
77 file
79 Full path to the file that contains the module
80 dir Directory, or more exact the @INC entry, where the module was
82 loaded from.
83 version
85 The version number of the installed module - this will be "undef"
86 if the module had no (or unparsable) version number, or if the
87 variable $Module::Load::Conditional::FIND_VERSION was set to true.
88 (See the "GLOBAL VARIABLES" section below for details)
89 uptodate
91 A boolean value indicating whether or not the module was found to
92 be at least the version you specified. If you did not specify a
93 version, uptodate will always be true if the module was found. If
94 no parsable version was found in the module, uptodate will also be
95 true, since "check_install" had no way to verify clearly.
96 See also $Module::Load::Conditional::DEPRECATED, which affects the
98 outcome of this value.
99 $bool = can_load( modules => { NAME => VERSION [,NAME => VERSION] },
101 [verbose => BOOL, nocache => BOOL] )
102 "can_load" will take a list of modules, optionally with version numbers
103 and determine if it is able to load them. If it can load *ALL* of them,
104 it will. If one or more are unloadable, none will be loaded.
105 This is particularly useful if you have More Than One Way (tm) to solve
107 a problem in a program, and only wish to continue down a path if all
108 modules could be loaded, and not load them if they couldn't.
109 This function uses the "load" function from Module::Load under the
111 hood.
112 "can_load" takes the following arguments:
114 modules
116 This is a hashref of module/version pairs. The version indicates
117 the minimum version to load. If no version is provided, any version
118 is assumed to be good enough.
119 verbose
121 This controls whether warnings should be printed if a module failed
122 to load. The default is to use the value of
123 $Module::Load::Conditional::VERBOSE.
124 nocache
126 "can_load" keeps its results in a cache, so it will not load the
127 same module twice, nor will it attempt to load a module that has
128 already failed to load before. By default, "can_load" will check
129 its cache, but you can override that by setting "nocache" to true.
130 @list = requires( MODULE );
132 "requires" can tell you what other modules a particular module
133 requires. This is particularly useful when you're intending to write a
134 module for public release and are listing its prerequisites.
135 "requires" takes but one argument: the name of a module. It will then
137 first check if it can actually load this module, and return undef if it
138 can't. Otherwise, it will return a list of modules and pragmas that
139 would have been loaded on the module's behalf.
140 Note: The list "require" returns has originated from your current perl
142 and your current install.
143
145 The behaviour of Module::Load::Conditional can be altered by changing
146 the following global variables:
147 $Module::Load::Conditional::VERBOSE
149 This controls whether Module::Load::Conditional will issue warnings and
150 explanations as to why certain things may have failed. If you set it to
151 0, Module::Load::Conditional will not output any warnings. The default
152 is 0;
153 $Module::Load::Conditional::FIND_VERSION
155 This controls whether Module::Load::Conditional will try to parse (and
156 eval) the version from the module you're trying to load.
157 If you don't wish to do this, set this variable to "false". Understand
159 then that version comparisons are not possible, and
160 Module::Load::Conditional can not tell you what module version you have
161 installed. This may be desirable from a security or performance point
162 of view. Note that $FIND_VERSION code runs safely under "taint mode".
163 The default is 1;
165 $Module::Load::Conditional::CHECK_INC_HASH
167 This controls whether "Module::Load::Conditional" checks your %INC hash
168 to see if a module is available. By default, only @INC is scanned to
169 see if a module is physically on your filesystem, or avialable via an
170 "@INC-hook". Setting this variable to "true" will trust any entries in
171 %INC and return them for you.
172 The default is 0;
174 $Module::Load::Conditional::CACHE
176 This holds the cache of the "can_load" function. If you explicitly want
177 to remove the current cache, you can set this variable to "undef"
178 $Module::Load::Conditional::ERROR
180 This holds a string of the last error that happened during a call to
181 "can_load". It is useful to inspect this when "can_load" returns
182 "undef".
183 $Module::Load::Conditional::DEPRECATED
185 This controls whether "Module::Load::Conditional" checks if a dual-life
186 core module has been deprecated. If this is set to true "check_install"
187 will return false to "uptodate", if a dual-life module is found to be
188 loaded from $Config{privlibexp}
189 The default is 0;
191
193 "Module::Load"
194
196 Please report bugs or other issues to
197 <bug-module-load-conditional@rt.cpan.org>.
198
200 This module by Jos Boumans <kane@cpan.org>.
201
203 This library is free software; you may redistribute and/or modify it
204 under the same terms as Perl itself.
205perl v5.12.4 2011-06-07 Module::Load::Conditional(3pm)