1Module::Load::ConditionUasle(r3)Contributed Perl DocumenMtoadtuiloen::Load::Conditional(3)
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
59 $href = check_install( module => NAME [, version => VERSION, verbose =>
60 BOOL ] );
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, autoload => 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 or the "autoload_remote"
111 function from Module::Load under the 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 autoload
132 This controls whether imports the functions of a loaded modules to
133 the caller package. The default is no importing any functions.
134 See the "autoload" function and the "autoload_remote" function from
136 Module::Load for details.
137 @list = requires( MODULE );
139 "requires" can tell you what other modules a particular module
140 requires. This is particularly useful when you're intending to write a
141 module for public release and are listing its prerequisites.
142 "requires" takes but one argument: the name of a module. It will then
144 first check if it can actually load this module, and return undef if it
145 can't. Otherwise, it will return a list of modules and pragmas that
146 would have been loaded on the module's behalf.
147 Note: The list "require" returns has originated from your current perl
149 and your current install.
150
152 The behaviour of Module::Load::Conditional can be altered by changing
153 the following global variables:
154 $Module::Load::Conditional::VERBOSE
156 This controls whether Module::Load::Conditional will issue warnings and
157 explanations as to why certain things may have failed. If you set it to
158 0, Module::Load::Conditional will not output any warnings. The default
159 is 0;
160 $Module::Load::Conditional::FIND_VERSION
162 This controls whether Module::Load::Conditional will try to parse (and
163 eval) the version from the module you're trying to load.
164 If you don't wish to do this, set this variable to "false". Understand
166 then that version comparisons are not possible, and
167 Module::Load::Conditional can not tell you what module version you have
168 installed. This may be desirable from a security or performance point
169 of view. Note that $FIND_VERSION code runs safely under "taint mode".
170 The default is 1;
172 $Module::Load::Conditional::CHECK_INC_HASH
174 This controls whether "Module::Load::Conditional" checks your %INC hash
175 to see if a module is available. By default, only @INC is scanned to
176 see if a module is physically on your filesystem, or available via an
177 "@INC-hook". Setting this variable to "true" will trust any entries in
178 %INC and return them for you.
179 The default is 0;
181 $Module::Load::Conditional::FORCE_SAFE_INC
183 This controls whether "Module::Load::Conditional" sanitises @INC by
184 removing ""."". The current default setting is 0, but this may change
185 in a future release.
186 $Module::Load::Conditional::CACHE
188 This holds the cache of the "can_load" function. If you explicitly want
189 to remove the current cache, you can set this variable to "undef"
190 $Module::Load::Conditional::ERROR
192 This holds a string of the last error that happened during a call to
193 "can_load". It is useful to inspect this when "can_load" returns
194 "undef".
195 $Module::Load::Conditional::DEPRECATED
197 This controls whether "Module::Load::Conditional" checks if a dual-life
198 core module has been deprecated. If this is set to true "check_install"
199 will return false to "uptodate", if a dual-life module is found to be
200 loaded from $Config{privlibexp}
201 The default is 0;
203
205 "Module::Load"
206
208 Please report bugs or other issues to
209 <bug-module-load-conditional@rt.cpan.org>.
210
212 This module by Jos Boumans <kane@cpan.org>.
213
215 This library is free software; you may redistribute and/or modify it
216 under the same terms as Perl itself.
217perl v5.38.0 2023-07-20 Module::Load::Conditional(3)