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

DESCRIPTION

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
54       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

Methods

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
64       module
65           The name of the module you wish to verify -- this is a required key
66
67       version
68           The version this module needs to be -- this is optional
69
70       verbose
71           Whether or not to be verbose about what it is doing -- it will
72           default to $Module::Load::Conditional::VERBOSE
73
74       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
78       file
79           Full path to the file that contains the module
80
81       dir Directory, or more exact the @INC entry, where the module was
82           loaded from.
83
84       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
90       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
97           See also $Module::Load::Conditional::DEPRECATED, which affects the
98           outcome of this value.
99
100   $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
106       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
110       This function uses the "load" function or the "autoload_remote"
111       function from Module::Load under the hood.
112
113       "can_load" takes the following arguments:
114
115       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
120       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
125       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
131       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
135           See the "autoload" function and the "autoload_remote" function from
136           Module::Load for details.
137
138   @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
143       "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
148       Note: The list "require" returns has originated from your current perl
149       and your current install.
150

Global Variables

152       The behaviour of Module::Load::Conditional can be altered by changing
153       the following global variables:
154
155   $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
161   $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
165       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
171       The default is 1;
172
173   $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
180       The default is 0;
181
182   $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
187   $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
191   $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
196   $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
202       The default is 0;
203

See Also

205       "Module::Load"
206

BUG REPORTS

208       Please report bugs or other issues to
209       <bug-module-load-conditional@rt.cpan.org>.
210

AUTHOR

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.
217
218
219
220perl v5.36.0                      2023-01-20      Module::Load::Conditional(3)
Impressum