1Module::Load::ConditionaPle(r3lpmP)rogrammers ReferenceMoGduuildee::Load::Conditional(3pm)
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

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

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
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] )
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 from Module::Load under the
111       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   @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
136       "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
141       Note: The list "require" returns has originated from your current perl
142       and your current install.
143

Global Variables

145       The behaviour of Module::Load::Conditional can be altered by changing
146       the following global variables:
147
148   $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
154   $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
158       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
164       The default is 1;
165
166   $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
173       The default is 0;
174
175   $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
179   $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
184   $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
190       The default is 0;
191

See Also

193       "Module::Load"
194

BUG REPORTS

196       Please report bugs or other issues to
197       <bug-module-load-conditional@rt.cpan.org>.
198

AUTHOR

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.
205
206
207
208perl v5.12.4                      2011-06-07    Module::Load::Conditional(3pm)
Impressum