local-lib5/man/man3/Module::Load::Conditional.3pm

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