Debian Codegraph @

upstream/mageia-cauldron/man3pm/Module::Load::Conditional.3pm

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