1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
|
.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Module::Load::Conditional 3pm"
.TH Module::Load::Conditional 3pm 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Module::Load::Conditional \- Looking up module information / loading at runtime
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\& use Module::Load::Conditional qw[can_load check_install requires];
\&
\&
\& my $use_list = {
\& CPANPLUS => 0.05,
\& LWP => 5.60,
\& \*(AqTest::More\*(Aq => undef,
\& };
\&
\& print can_load( modules => $use_list )
\& ? \*(Aqall modules loaded successfully\*(Aq
\& : \*(Aqfailed to load required modules\*(Aq;
\&
\&
\& my $rv = check_install( module => \*(AqLWP\*(Aq, version => 5.60 )
\& or print \*(AqLWP is not installed!\*(Aq;
\&
\& print \*(AqLWP up to date\*(Aq if $rv\->{uptodate};
\& print "LWP version is $rv\->{version}\en";
\& print "LWP is installed as file $rv\->{file}\en";
\&
\&
\& print "LWP requires the following modules to be installed:\en";
\& print join "\en", requires(\*(AqLWP\*(Aq);
\&
\& ### allow M::L::C to peek in your %INC rather than just
\& ### scanning @INC
\& $Module::Load::Conditional::CHECK_INC_HASH = 1;
\&
\& ### reset the \*(Aqcan_load\*(Aq cache
\& undef $Module::Load::Conditional::CACHE;
\&
\& ### don\*(Aqt have Module::Load::Conditional issue warnings \-\-
\& ### default is \*(Aq1\*(Aq
\& $Module::Load::Conditional::VERBOSE = 0;
\&
\& ### The last error that happened during a call to \*(Aqcan_load\*(Aq
\& my $err = $Module::Load::Conditional::ERROR;
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
Module::Load::Conditional provides simple ways to query and possibly load any of
the modules you have installed on your system during runtime.
.PP
It is able to load multiple modules at once or none at all if one of
them was not able to load. It also takes care of any error checking
and so forth.
.SH Methods
.IX Header "Methods"
.ie n .SS "$href = check_install( module => NAME [, version => VERSION, verbose => BOOL ] );"
.el .SS "\f(CW$href\fP = check_install( module => NAME [, version => VERSION, verbose => BOOL ] );"
.IX Subsection "$href = check_install( module => NAME [, version => VERSION, verbose => BOOL ] );"
\&\f(CW\*(C`check_install\*(C'\fR allows you to verify if a certain module is installed
or not. You may call it with the following arguments:
.IP module 4
.IX Item "module"
The name of the module you wish to verify \-\- this is a required key
.IP version 4
.IX Item "version"
The version this module needs to be \-\- this is optional
.IP verbose 4
.IX Item "verbose"
Whether or not to be verbose about what it is doing \-\- it will default
to \f(CW$Module::Load::Conditional::VERBOSE\fR
.PP
It will return undef if it was not able to find where the module was
installed, or a hash reference with the following keys if it was able
to find the file:
.IP file 4
.IX Item "file"
Full path to the file that contains the module
.IP dir 4
.IX Item "dir"
Directory, or more exact the \f(CW@INC\fR entry, where the module was
loaded from.
.IP version 4
.IX Item "version"
The version number of the installed module \- this will be \f(CW\*(C`undef\*(C'\fR if
the module had no (or unparsable) version number, or if the variable
\&\f(CW$Module::Load::Conditional::FIND_VERSION\fR was set to true.
(See the \f(CW\*(C`GLOBAL VARIABLES\*(C'\fR section below for details)
.IP uptodate 4
.IX Item "uptodate"
A boolean value indicating whether or not the module was found to be
at least the version you specified. If you did not specify a version,
uptodate will always be true if the module was found.
If no parsable version was found in the module, uptodate will also be
true, since \f(CW\*(C`check_install\*(C'\fR had no way to verify clearly.
.Sp
See also \f(CW$Module::Load::Conditional::DEPRECATED\fR, which affects
the outcome of this value.
.ie n .SS "$bool = can_load( modules => { NAME => VERSION [,NAME => VERSION] }, [verbose => BOOL, nocache => BOOL, autoload => BOOL] )"
.el .SS "\f(CW$bool\fP = can_load( modules => { NAME => VERSION [,NAME => VERSION] }, [verbose => BOOL, nocache => BOOL, autoload => BOOL] )"
.IX Subsection "$bool = can_load( modules => { NAME => VERSION [,NAME => VERSION] }, [verbose => BOOL, nocache => BOOL, autoload => BOOL] )"
\&\f(CW\*(C`can_load\*(C'\fR will take a list of modules, optionally with version
numbers and determine if it is able to load them. If it can load *ALL*
of them, it will. If one or more are unloadable, none will be loaded.
.PP
This is particularly useful if you have More Than One Way (tm) to
solve a problem in a program, and only wish to continue down a path
if all modules could be loaded, and not load them if they couldn't.
.PP
This function uses the \f(CW\*(C`load\*(C'\fR function or the \f(CW\*(C`autoload_remote\*(C'\fR function
from Module::Load under the hood.
.PP
\&\f(CW\*(C`can_load\*(C'\fR takes the following arguments:
.IP modules 4
.IX Item "modules"
This is a hashref of module/version pairs. The version indicates the
minimum version to load. If no version is provided, any version is
assumed to be good enough.
.IP verbose 4
.IX Item "verbose"
This controls whether warnings should be printed if a module failed
to load.
The default is to use the value of \f(CW$Module::Load::Conditional::VERBOSE\fR.
.IP nocache 4
.IX Item "nocache"
\&\f(CW\*(C`can_load\*(C'\fR keeps its results in a cache, so it will not load the
same module twice, nor will it attempt to load a module that has
already failed to load before. By default, \f(CW\*(C`can_load\*(C'\fR will check its
cache, but you can override that by setting \f(CW\*(C`nocache\*(C'\fR to true.
.IP autoload 4
.IX Item "autoload"
This controls whether imports the functions of a loaded modules to the caller package. The default is no importing any functions.
.Sp
See the \f(CW\*(C`autoload\*(C'\fR function and the \f(CW\*(C`autoload_remote\*(C'\fR function from Module::Load for details.
.ie n .SS "@list = requires( MODULE );"
.el .SS "\f(CW@list\fP = requires( MODULE );"
.IX Subsection "@list = requires( MODULE );"
\&\f(CW\*(C`requires\*(C'\fR can tell you what other modules a particular module
requires. This is particularly useful when you're intending to write
a module for public release and are listing its prerequisites.
.PP
\&\f(CW\*(C`requires\*(C'\fR takes but one argument: the name of a module.
It will then first check if it can actually load this module, and
return undef if it can't.
Otherwise, it will return a list of modules and pragmas that would
have been loaded on the module's behalf.
.PP
Note: The list \f(CW\*(C`require\*(C'\fR returns has originated from your current
perl and your current install.
.SH "Global Variables"
.IX Header "Global Variables"
The behaviour of Module::Load::Conditional can be altered by changing the
following global variables:
.ie n .SS $Module::Load::Conditional::VERBOSE
.el .SS \f(CW$Module::Load::Conditional::VERBOSE\fP
.IX Subsection "$Module::Load::Conditional::VERBOSE"
This controls whether Module::Load::Conditional will issue warnings and
explanations as to why certain things may have failed. If you set it
to 0, Module::Load::Conditional will not output any warnings.
The default is 0;
.ie n .SS $Module::Load::Conditional::FIND_VERSION
.el .SS \f(CW$Module::Load::Conditional::FIND_VERSION\fP
.IX Subsection "$Module::Load::Conditional::FIND_VERSION"
This controls whether Module::Load::Conditional will try to parse
(and eval) the version from the module you're trying to load.
.PP
If you don't wish to do this, set this variable to \f(CW\*(C`false\*(C'\fR. Understand
then that version comparisons are not possible, and Module::Load::Conditional
can not tell you what module version you have installed.
This may be desirable from a security or performance point of view.
Note that \f(CW$FIND_VERSION\fR code runs safely under \f(CW\*(C`taint mode\*(C'\fR.
.PP
The default is 1;
.ie n .SS $Module::Load::Conditional::CHECK_INC_HASH
.el .SS \f(CW$Module::Load::Conditional::CHECK_INC_HASH\fP
.IX Subsection "$Module::Load::Conditional::CHECK_INC_HASH"
This controls whether \f(CW\*(C`Module::Load::Conditional\*(C'\fR checks your
\&\f(CW%INC\fR hash to see if a module is available. By default, only
\&\f(CW@INC\fR is scanned to see if a module is physically on your
filesystem, or available via an \f(CW\*(C`@INC\-hook\*(C'\fR. Setting this variable
to \f(CW\*(C`true\*(C'\fR will trust any entries in \f(CW%INC\fR and return them for
you.
.PP
The default is 0;
.ie n .SS $Module::Load::Conditional::FORCE_SAFE_INC
.el .SS \f(CW$Module::Load::Conditional::FORCE_SAFE_INC\fP
.IX Subsection "$Module::Load::Conditional::FORCE_SAFE_INC"
This controls whether \f(CW\*(C`Module::Load::Conditional\*(C'\fR sanitises \f(CW@INC\fR
by removing "\f(CW\*(C`.\*(C'\fR". The current default setting is \f(CW0\fR, but this
may change in a future release.
.ie n .SS $Module::Load::Conditional::CACHE
.el .SS \f(CW$Module::Load::Conditional::CACHE\fP
.IX Subsection "$Module::Load::Conditional::CACHE"
This holds the cache of the \f(CW\*(C`can_load\*(C'\fR function. If you explicitly
want to remove the current cache, you can set this variable to
\&\f(CW\*(C`undef\*(C'\fR
.ie n .SS $Module::Load::Conditional::ERROR
.el .SS \f(CW$Module::Load::Conditional::ERROR\fP
.IX Subsection "$Module::Load::Conditional::ERROR"
This holds a string of the last error that happened during a call to
\&\f(CW\*(C`can_load\*(C'\fR. It is useful to inspect this when \f(CW\*(C`can_load\*(C'\fR returns
\&\f(CW\*(C`undef\*(C'\fR.
.ie n .SS $Module::Load::Conditional::DEPRECATED
.el .SS \f(CW$Module::Load::Conditional::DEPRECATED\fP
.IX Subsection "$Module::Load::Conditional::DEPRECATED"
This controls whether \f(CW\*(C`Module::Load::Conditional\*(C'\fR checks if
a dual-life core module has been deprecated. If this is set to
true \f(CW\*(C`check_install\*(C'\fR will return false to \f(CW\*(C`uptodate\*(C'\fR, if
a dual-life module is found to be loaded from \f(CW$Config{privlibexp}\fR
.PP
The default is 0;
.SH "See Also"
.IX Header "See Also"
\&\f(CW\*(C`Module::Load\*(C'\fR
.SH "BUG REPORTS"
.IX Header "BUG REPORTS"
Please report bugs or other issues to <bug\-module\-load\-conditional@rt.cpan.org>.
.SH AUTHOR
.IX Header "AUTHOR"
This module by Jos Boumans <kane@cpan.org>.
.SH COPYRIGHT
.IX Header "COPYRIGHT"
This library is free software; you may redistribute and/or modify it
under the same terms as Perl itself.
|
