| 1 | package Params::Util; | ||||||||||
| 2 | |||||||||||
| 3 | =pod | ||||||||||
| 4 | |||||||||||
| 5 | =head1 NAME | ||||||||||
| 6 | |||||||||||
| 7 | Params::Util - Simple, compact and correct param-checking functions | ||||||||||
| 8 | |||||||||||
| 9 | =head1 SYNOPSIS | ||||||||||
| 10 | |||||||||||
| 11 | # Import some functions | ||||||||||
| 12 | use Params::Util qw{_SCALAR _HASH _INSTANCE}; | ||||||||||
| 13 | |||||||||||
| 14 | # If you are lazy, or need a lot of them... | ||||||||||
| 15 | use Params::Util ':ALL'; | ||||||||||
| 16 | |||||||||||
| 17 | sub foo { | ||||||||||
| 18 | my $object = _INSTANCE(shift, 'Foo') or return undef; | ||||||||||
| 19 | my $image = _SCALAR(shift) or return undef; | ||||||||||
| 20 | my $options = _HASH(shift) or return undef; | ||||||||||
| 21 | # etc... | ||||||||||
| 22 | } | ||||||||||
| 23 | |||||||||||
| 24 | =head1 DESCRIPTION | ||||||||||
| 25 | |||||||||||
| 26 | C<Params::Util> provides a basic set of importable functions that makes | ||||||||||
| 27 | checking parameters a hell of a lot easier | ||||||||||
| 28 | |||||||||||
| 29 | While they can be (and are) used in other contexts, the main point | ||||||||||
| 30 | behind this module is that the functions B<both> Do What You Mean, | ||||||||||
| 31 | and Do The Right Thing, so they are most useful when you are getting | ||||||||||
| 32 | params passed into your code from someone and/or somewhere else | ||||||||||
| 33 | and you can't really trust the quality. | ||||||||||
| 34 | |||||||||||
| 35 | Thus, C<Params::Util> is of most use at the edges of your API, where | ||||||||||
| 36 | params and data are coming in from outside your code. | ||||||||||
| 37 | |||||||||||
| 38 | The functions provided by C<Params::Util> check in the most strictly | ||||||||||
| 39 | correct manner known, are documented as thoroughly as possible so their | ||||||||||
| 40 | exact behaviour is clear, and heavily tested so make sure they are not | ||||||||||
| 41 | fooled by weird data and Really Bad Things. | ||||||||||
| 42 | |||||||||||
| 43 | To use, simply load the module providing the functions you want to use | ||||||||||
| 44 | as arguments (as shown in the SYNOPSIS). | ||||||||||
| 45 | |||||||||||
| 46 | To aid in maintainability, C<Params::Util> will B<never> export by | ||||||||||
| 47 | default. | ||||||||||
| 48 | |||||||||||
| 49 | You must explicitly name the functions you want to export, or use the | ||||||||||
| 50 | C<:ALL> param to just have it export everything (although this is not | ||||||||||
| 51 | recommended if you have any _FOO functions yourself with which future | ||||||||||
| 52 | additions to C<Params::Util> may clash) | ||||||||||
| 53 | |||||||||||
| 54 | =head1 FUNCTIONS | ||||||||||
| 55 | |||||||||||
| 56 | =cut | ||||||||||
| 57 | |||||||||||
| 58 | 18 | ▶ | use 5.00503; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 59 | 18 | ▶ | use strict; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 60 | 18 | ▶ | use warnings; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 61 | 18 | ▶ | use parent qw{Exporter XSLoader}; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 62 | |||||||||||
| 63 | 18 | ▶ | use Params::Util::PP qw(); | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 64 | |||||||||||
| 65 | 18 | our $VERSION = '1.099_001'; | |||||||||
| 66 | |||||||||||
| 67 | 18 | ▶ | local $ENV{PERL_DL_NONLAZY} = 0 if $ENV{PERL_DL_NONLAZY}; | ||||||||
|
Branch: 1 branch
| |||||||||||
| 68 | 18 | ▶ | XSLoader::load("Params::Util", $VERSION) unless $ENV{PERL_PARAMS_UTIL_PP}; | ||||||||
|
Branch: 1 branch
| |||||||||||
| 69 | |||||||||||
| 70 | 18 | our @EXPORT_OK = qw{ | |||||||||
| 71 | _STRING _IDENTIFIER | ||||||||||
| 72 | _CLASS _CLASSISA _SUBCLASS _DRIVER _CLASSDOES | ||||||||||
| 73 | _NUMBER _POSINT _NONNEGINT | ||||||||||
| 74 | _SCALAR _SCALAR0 | ||||||||||
| 75 | _ARRAY _ARRAY0 _ARRAYLIKE | ||||||||||
| 76 | _HASH _HASH0 _HASHLIKE | ||||||||||
| 77 | _CODE _CODELIKE | ||||||||||
| 78 | _INVOCANT _REGEX _INSTANCE _INSTANCEDOES | ||||||||||
| 79 | _SET _SET0 | ||||||||||
| 80 | _HANDLE | ||||||||||
| 81 | }; | ||||||||||
| 82 | 18 | our %EXPORT_TAGS = (ALL => \@EXPORT_OK); | |||||||||
| 83 | |||||||||||
| 84 | ## no critic (TestingAndDebugging::ProhibitNoStrict) | ||||||||||
| 85 | 18 | ▶ | no strict "refs"; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 86 | 18 | ▶ | Params::Util->can($_) or *$_ = Params::Util::PP->can($_) for (@EXPORT_OK); | ||||||||
|
Branch: 1 branch
| |||||||||||
| 87 | 18 | ▶ | use strict "refs"; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 88 | |||||||||||
| 89 | ##################################################################### | ||||||||||
| 90 | # Param Checking Functions | ||||||||||
| 91 | |||||||||||
| 92 | =pod | ||||||||||
| 93 | |||||||||||
| 94 | =head2 _STRING $string | ||||||||||
| 95 | |||||||||||
| 96 | The C<_STRING> function is intended to be imported into your | ||||||||||
| 97 | package, and provides a convenient way to test to see if a value is | ||||||||||
| 98 | a normal non-false string of non-zero length. | ||||||||||
| 99 | |||||||||||
| 100 | Note that this will NOT do anything magic to deal with the special | ||||||||||
| 101 | C<'0'> false negative case, but will return it. | ||||||||||
| 102 | |||||||||||
| 103 | # '0' not considered valid data | ||||||||||
| 104 | my $name = _STRING(shift) or die "Bad name"; | ||||||||||
| 105 | |||||||||||
| 106 | # '0' is considered valid data | ||||||||||
| 107 | my $string = _STRING($_[0]) ? shift : die "Bad string"; | ||||||||||
| 108 | |||||||||||
| 109 | Please also note that this function expects a normal string. It does | ||||||||||
| 110 | not support overloading or other magic techniques to get a string. | ||||||||||
| 111 | |||||||||||
| 112 | Returns the string as a convenience if it is a valid string, or | ||||||||||
| 113 | C<undef> if not. | ||||||||||
| 114 | |||||||||||
| 115 | =head2 _IDENTIFIER $string | ||||||||||
| 116 | |||||||||||
| 117 | The C<_IDENTIFIER> function is intended to be imported into your | ||||||||||
| 118 | package, and provides a convenient way to test to see if a value is | ||||||||||
| 119 | a string that is a valid Perl identifier. | ||||||||||
| 120 | |||||||||||
| 121 | Returns the string as a convenience if it is a valid identifier, or | ||||||||||
| 122 | C<undef> if not. | ||||||||||
| 123 | |||||||||||
| 124 | =head2 _CLASS $string | ||||||||||
| 125 | |||||||||||
| 126 | The C<_CLASS> function is intended to be imported into your | ||||||||||
| 127 | package, and provides a convenient way to test to see if a value is | ||||||||||
| 128 | a string that is a valid Perl class. | ||||||||||
| 129 | |||||||||||
| 130 | This function only checks that the format is valid, not that the | ||||||||||
| 131 | class is actually loaded. It also assumes "normalized" form, and does | ||||||||||
| 132 | not accept class names such as C<::Foo> or C<D'Oh>. | ||||||||||
| 133 | |||||||||||
| 134 | Returns the string as a convenience if it is a valid class name, or | ||||||||||
| 135 | C<undef> if not. | ||||||||||
| 136 | |||||||||||
| 137 | =head2 _CLASSISA $string, $class | ||||||||||
| 138 | |||||||||||
| 139 | The C<_CLASSISA> function is intended to be imported into your | ||||||||||
| 140 | package, and provides a convenient way to test to see if a value is | ||||||||||
| 141 | a string that is a particularly class, or a subclass of it. | ||||||||||
| 142 | |||||||||||
| 143 | This function checks that the format is valid and calls the -E<gt>isa | ||||||||||
| 144 | method on the class name. It does not check that the class is actually | ||||||||||
| 145 | loaded. | ||||||||||
| 146 | |||||||||||
| 147 | It also assumes "normalized" form, and does | ||||||||||
| 148 | not accept class names such as C<::Foo> or C<D'Oh>. | ||||||||||
| 149 | |||||||||||
| 150 | Returns the string as a convenience if it is a valid class name, or | ||||||||||
| 151 | C<undef> if not. | ||||||||||
| 152 | |||||||||||
| 153 | =head2 _CLASSDOES $string, $role | ||||||||||
| 154 | |||||||||||
| 155 | This routine behaves exactly like C<L</_CLASSISA>>, but checks with C<< ->DOES | ||||||||||
| 156 | >> rather than C<< ->isa >>. This is probably only a good idea to use on Perl | ||||||||||
| 157 | 5.10 or later, when L<UNIVERSAL::DOES|UNIVERSAL::DOES/DOES> has been | ||||||||||
| 158 | implemented. | ||||||||||
| 159 | |||||||||||
| 160 | =head2 _SUBCLASS $string, $class | ||||||||||
| 161 | |||||||||||
| 162 | The C<_SUBCLASS> function is intended to be imported into your | ||||||||||
| 163 | package, and provides a convenient way to test to see if a value is | ||||||||||
| 164 | a string that is a subclass of a specified class. | ||||||||||
| 165 | |||||||||||
| 166 | This function checks that the format is valid and calls the -E<gt>isa | ||||||||||
| 167 | method on the class name. It does not check that the class is actually | ||||||||||
| 168 | loaded. | ||||||||||
| 169 | |||||||||||
| 170 | It also assumes "normalized" form, and does | ||||||||||
| 171 | not accept class names such as C<::Foo> or C<D'Oh>. | ||||||||||
| 172 | |||||||||||
| 173 | Returns the string as a convenience if it is a valid class name, or | ||||||||||
| 174 | C<undef> if not. | ||||||||||
| 175 | |||||||||||
| 176 | =head2 _NUMBER $scalar | ||||||||||
| 177 | |||||||||||
| 178 | The C<_NUMBER> function is intended to be imported into your | ||||||||||
| 179 | package, and provides a convenient way to test to see if a value is | ||||||||||
| 180 | a number. That is, it is defined and perl thinks it's a number. | ||||||||||
| 181 | |||||||||||
| 182 | This function is basically a Params::Util-style wrapper around the | ||||||||||
| 183 | L<Scalar::Util> C<looks_like_number> function. | ||||||||||
| 184 | |||||||||||
| 185 | Returns the value as a convenience, or C<undef> if the value is not a | ||||||||||
| 186 | number. | ||||||||||
| 187 | |||||||||||
| 188 | =head2 _POSINT $integer | ||||||||||
| 189 | |||||||||||
| 190 | The C<_POSINT> function is intended to be imported into your | ||||||||||
| 191 | package, and provides a convenient way to test to see if a value is | ||||||||||
| 192 | a positive integer (of any length). | ||||||||||
| 193 | |||||||||||
| 194 | Returns the value as a convenience, or C<undef> if the value is not a | ||||||||||
| 195 | positive integer. | ||||||||||
| 196 | |||||||||||
| 197 | The name itself is derived from the XML schema constraint of the same | ||||||||||
| 198 | name. | ||||||||||
| 199 | |||||||||||
| 200 | =head2 _NONNEGINT $integer | ||||||||||
| 201 | |||||||||||
| 202 | The C<_NONNEGINT> function is intended to be imported into your | ||||||||||
| 203 | package, and provides a convenient way to test to see if a value is | ||||||||||
| 204 | a non-negative integer (of any length). That is, a positive integer, | ||||||||||
| 205 | or zero. | ||||||||||
| 206 | |||||||||||
| 207 | Returns the value as a convenience, or C<undef> if the value is not a | ||||||||||
| 208 | non-negative integer. | ||||||||||
| 209 | |||||||||||
| 210 | As with other tests that may return false values, care should be taken | ||||||||||
| 211 | to test via "defined" in boolean validly contexts. | ||||||||||
| 212 | |||||||||||
| 213 | unless ( defined _NONNEGINT($value) ) { | ||||||||||
| 214 | die "Invalid value"; | ||||||||||
| 215 | } | ||||||||||
| 216 | |||||||||||
| 217 | The name itself is derived from the XML schema constraint of the same | ||||||||||
| 218 | name. | ||||||||||
| 219 | |||||||||||
| 220 | =head2 _SCALAR \$scalar | ||||||||||
| 221 | |||||||||||
| 222 | The C<_SCALAR> function is intended to be imported into your package, | ||||||||||
| 223 | and provides a convenient way to test for a raw and unblessed | ||||||||||
| 224 | C<SCALAR> reference, with content of non-zero length. | ||||||||||
| 225 | |||||||||||
| 226 | For a version that allows zero length C<SCALAR> references, see | ||||||||||
| 227 | the C<_SCALAR0> function. | ||||||||||
| 228 | |||||||||||
| 229 | Returns the C<SCALAR> reference itself as a convenience, or C<undef> | ||||||||||
| 230 | if the value provided is not a C<SCALAR> reference. | ||||||||||
| 231 | |||||||||||
| 232 | =head2 _SCALAR0 \$scalar | ||||||||||
| 233 | |||||||||||
| 234 | The C<_SCALAR0> function is intended to be imported into your package, | ||||||||||
| 235 | and provides a convenient way to test for a raw and unblessed | ||||||||||
| 236 | C<SCALAR0> reference, allowing content of zero-length. | ||||||||||
| 237 | |||||||||||
| 238 | For a simpler "give me some content" version that requires non-zero | ||||||||||
| 239 | length, C<_SCALAR> function. | ||||||||||
| 240 | |||||||||||
| 241 | Returns the C<SCALAR> reference itself as a convenience, or C<undef> | ||||||||||
| 242 | if the value provided is not a C<SCALAR> reference. | ||||||||||
| 243 | |||||||||||
| 244 | =head2 _ARRAY $value | ||||||||||
| 245 | |||||||||||
| 246 | The C<_ARRAY> function is intended to be imported into your package, | ||||||||||
| 247 | and provides a convenient way to test for a raw and unblessed | ||||||||||
| 248 | C<ARRAY> reference containing B<at least> one element of any kind. | ||||||||||
| 249 | |||||||||||
| 250 | For a more basic form that allows zero length ARRAY references, see | ||||||||||
| 251 | the C<_ARRAY0> function. | ||||||||||
| 252 | |||||||||||
| 253 | Returns the C<ARRAY> reference itself as a convenience, or C<undef> | ||||||||||
| 254 | if the value provided is not an C<ARRAY> reference. | ||||||||||
| 255 | |||||||||||
| 256 | =head2 _ARRAY0 $value | ||||||||||
| 257 | |||||||||||
| 258 | The C<_ARRAY0> function is intended to be imported into your package, | ||||||||||
| 259 | and provides a convenient way to test for a raw and unblessed | ||||||||||
| 260 | C<ARRAY> reference, allowing C<ARRAY> references that contain no | ||||||||||
| 261 | elements. | ||||||||||
| 262 | |||||||||||
| 263 | For a more basic "An array of something" form that also requires at | ||||||||||
| 264 | least one element, see the C<_ARRAY> function. | ||||||||||
| 265 | |||||||||||
| 266 | Returns the C<ARRAY> reference itself as a convenience, or C<undef> | ||||||||||
| 267 | if the value provided is not an C<ARRAY> reference. | ||||||||||
| 268 | |||||||||||
| 269 | =head2 _ARRAYLIKE $value | ||||||||||
| 270 | |||||||||||
| 271 | The C<_ARRAYLIKE> function tests whether a given scalar value can respond to | ||||||||||
| 272 | array dereferencing. If it can, the value is returned. If it cannot, | ||||||||||
| 273 | C<_ARRAYLIKE> returns C<undef>. | ||||||||||
| 274 | |||||||||||
| 275 | =head2 _HASH $value | ||||||||||
| 276 | |||||||||||
| 277 | The C<_HASH> function is intended to be imported into your package, | ||||||||||
| 278 | and provides a convenient way to test for a raw and unblessed | ||||||||||
| 279 | C<HASH> reference with at least one entry. | ||||||||||
| 280 | |||||||||||
| 281 | For a version of this function that allows the C<HASH> to be empty, | ||||||||||
| 282 | see the C<_HASH0> function. | ||||||||||
| 283 | |||||||||||
| 284 | Returns the C<HASH> reference itself as a convenience, or C<undef> | ||||||||||
| 285 | if the value provided is not an C<HASH> reference. | ||||||||||
| 286 | |||||||||||
| 287 | =head2 _HASH0 $value | ||||||||||
| 288 | |||||||||||
| 289 | The C<_HASH0> function is intended to be imported into your package, | ||||||||||
| 290 | and provides a convenient way to test for a raw and unblessed | ||||||||||
| 291 | C<HASH> reference, regardless of the C<HASH> content. | ||||||||||
| 292 | |||||||||||
| 293 | For a simpler "A hash of something" version that requires at least one | ||||||||||
| 294 | element, see the C<_HASH> function. | ||||||||||
| 295 | |||||||||||
| 296 | Returns the C<HASH> reference itself as a convenience, or C<undef> | ||||||||||
| 297 | if the value provided is not an C<HASH> reference. | ||||||||||
| 298 | |||||||||||
| 299 | =head2 _HASHLIKE $value | ||||||||||
| 300 | |||||||||||
| 301 | The C<_HASHLIKE> function tests whether a given scalar value can respond to | ||||||||||
| 302 | hash dereferencing. If it can, the value is returned. If it cannot, | ||||||||||
| 303 | C<_HASHLIKE> returns C<undef>. | ||||||||||
| 304 | |||||||||||
| 305 | =head2 _CODE $value | ||||||||||
| 306 | |||||||||||
| 307 | The C<_CODE> function is intended to be imported into your package, | ||||||||||
| 308 | and provides a convenient way to test for a raw and unblessed | ||||||||||
| 309 | C<CODE> reference. | ||||||||||
| 310 | |||||||||||
| 311 | Returns the C<CODE> reference itself as a convenience, or C<undef> | ||||||||||
| 312 | if the value provided is not an C<CODE> reference. | ||||||||||
| 313 | |||||||||||
| 314 | =head2 _CODELIKE $value | ||||||||||
| 315 | |||||||||||
| 316 | The C<_CODELIKE> is the more generic version of C<_CODE>. Unlike C<_CODE>, | ||||||||||
| 317 | which checks for an explicit C<CODE> reference, the C<_CODELIKE> function | ||||||||||
| 318 | also includes things that act like them, such as blessed objects that | ||||||||||
| 319 | overload C<'&{}'>. | ||||||||||
| 320 | |||||||||||
| 321 | Please note that in the case of objects overloaded with '&{}', you will | ||||||||||
| 322 | almost always end up also testing it in 'bool' context at some stage. | ||||||||||
| 323 | |||||||||||
| 324 | For example: | ||||||||||
| 325 | |||||||||||
| 326 | sub foo { | ||||||||||
| 327 | my $code1 = _CODELIKE(shift) or die "No code param provided"; | ||||||||||
| 328 | my $code2 = _CODELIKE(shift); | ||||||||||
| 329 | if ( $code2 ) { | ||||||||||
| 330 | print "Got optional second code param"; | ||||||||||
| 331 | } | ||||||||||
| 332 | } | ||||||||||
| 333 | |||||||||||
| 334 | As such, you will most likely always want to make sure your class has | ||||||||||
| 335 | at least the following to allow it to evaluate to true in boolean | ||||||||||
| 336 | context. | ||||||||||
| 337 | |||||||||||
| 338 | # Always evaluate to true in boolean context | ||||||||||
| 339 | use overload 'bool' => sub () { 1 }; | ||||||||||
| 340 | |||||||||||
| 341 | Returns the callable value as a convenience, or C<undef> if the | ||||||||||
| 342 | value provided is not callable. | ||||||||||
| 343 | |||||||||||
| 344 | Note - This function was formerly known as _CALLABLE but has been renamed | ||||||||||
| 345 | for greater symmetry with the other _XXXXLIKE functions. | ||||||||||
| 346 | |||||||||||
| 347 | The use of _CALLABLE has been deprecated. It will continue to work, but | ||||||||||
| 348 | with a warning, until end-2006, then will be removed. | ||||||||||
| 349 | |||||||||||
| 350 | I apologize for any inconvenience caused. | ||||||||||
| 351 | |||||||||||
| 352 | =head2 _INVOCANT $value | ||||||||||
| 353 | |||||||||||
| 354 | This routine tests whether the given value is a valid method invocant. | ||||||||||
| 355 | This can be either an instance of an object, or a class name. | ||||||||||
| 356 | |||||||||||
| 357 | If so, the value itself is returned. Otherwise, C<_INVOCANT> | ||||||||||
| 358 | returns C<undef>. | ||||||||||
| 359 | |||||||||||
| 360 | =head2 _INSTANCE $object, $class | ||||||||||
| 361 | |||||||||||
| 362 | The C<_INSTANCE> function is intended to be imported into your package, | ||||||||||
| 363 | and provides a convenient way to test for an object of a particular class | ||||||||||
| 364 | in a strictly correct manner. | ||||||||||
| 365 | |||||||||||
| 366 | Returns the object itself as a convenience, or C<undef> if the value | ||||||||||
| 367 | provided is not an object of that type. | ||||||||||
| 368 | |||||||||||
| 369 | =head2 _INSTANCEDOES $object, $role | ||||||||||
| 370 | |||||||||||
| 371 | This routine behaves exactly like C<L</_INSTANCE>>, but checks with C<< ->DOES | ||||||||||
| 372 | >> rather than C<< ->isa >>. This is probably only a good idea to use on Perl | ||||||||||
| 373 | 5.10 or later, when L<UNIVERSAL::DOES|UNIVERSAL::DOES/DOES> has been | ||||||||||
| 374 | implemented. | ||||||||||
| 375 | |||||||||||
| 376 | =head2 _REGEX $value | ||||||||||
| 377 | |||||||||||
| 378 | The C<_REGEX> function is intended to be imported into your package, | ||||||||||
| 379 | and provides a convenient way to test for a regular expression. | ||||||||||
| 380 | |||||||||||
| 381 | Returns the value itself as a convenience, or C<undef> if the value | ||||||||||
| 382 | provided is not a regular expression. | ||||||||||
| 383 | |||||||||||
| 384 | =head2 _SET \@array, $class | ||||||||||
| 385 | |||||||||||
| 386 | The C<_SET> function is intended to be imported into your package, | ||||||||||
| 387 | and provides a convenient way to test for set of at least one object of | ||||||||||
| 388 | a particular class in a strictly correct manner. | ||||||||||
| 389 | |||||||||||
| 390 | The set is provided as a reference to an C<ARRAY> of objects of the | ||||||||||
| 391 | class provided. | ||||||||||
| 392 | |||||||||||
| 393 | For an alternative function that allows zero-length sets, see the | ||||||||||
| 394 | C<_SET0> function. | ||||||||||
| 395 | |||||||||||
| 396 | Returns the C<ARRAY> reference itself as a convenience, or C<undef> if | ||||||||||
| 397 | the value provided is not a set of that class. | ||||||||||
| 398 | |||||||||||
| 399 | =head2 _SET0 \@array, $class | ||||||||||
| 400 | |||||||||||
| 401 | The C<_SET0> function is intended to be imported into your package, | ||||||||||
| 402 | and provides a convenient way to test for a set of objects of a | ||||||||||
| 403 | particular class in a strictly correct manner, allowing for zero objects. | ||||||||||
| 404 | |||||||||||
| 405 | The set is provided as a reference to an C<ARRAY> of objects of the | ||||||||||
| 406 | class provided. | ||||||||||
| 407 | |||||||||||
| 408 | For an alternative function that requires at least one object, see the | ||||||||||
| 409 | C<_SET> function. | ||||||||||
| 410 | |||||||||||
| 411 | Returns the C<ARRAY> reference itself as a convenience, or C<undef> if | ||||||||||
| 412 | the value provided is not a set of that class. | ||||||||||
| 413 | |||||||||||
| 414 | =head2 _HANDLE | ||||||||||
| 415 | |||||||||||
| 416 | The C<_HANDLE> function is intended to be imported into your package, | ||||||||||
| 417 | and provides a convenient way to test whether or not a single scalar | ||||||||||
| 418 | value is a file handle. | ||||||||||
| 419 | |||||||||||
| 420 | Unfortunately, in Perl the definition of a file handle can be a little | ||||||||||
| 421 | bit fuzzy, so this function is likely to be somewhat imperfect (at first | ||||||||||
| 422 | anyway). | ||||||||||
| 423 | |||||||||||
| 424 | That said, it is implement as well or better than the other file handle | ||||||||||
| 425 | detectors in existence (and we stole from the best of them). | ||||||||||
| 426 | |||||||||||
| 427 | =head2 _DRIVER $string | ||||||||||
| 428 | |||||||||||
| 429 | sub foo { | ||||||||||
| 430 | my $class = _DRIVER(shift, 'My::Driver::Base') or die "Bad driver"; | ||||||||||
| 431 | ... | ||||||||||
| 432 | } | ||||||||||
| 433 | |||||||||||
| 434 | The C<_DRIVER> function is intended to be imported into your | ||||||||||
| 435 | package, and provides a convenient way to load and validate | ||||||||||
| 436 | a driver class. | ||||||||||
| 437 | |||||||||||
| 438 | The most common pattern when taking a driver class as a parameter | ||||||||||
| 439 | is to check that the name is a class (i.e. check against _CLASS) | ||||||||||
| 440 | and then to load the class (if it exists) and then ensure that | ||||||||||
| 441 | the class returns true for the isa method on some base driver name. | ||||||||||
| 442 | |||||||||||
| 443 | Return the value as a convenience, or C<undef> if the value is not | ||||||||||
| 444 | a class name, the module does not exist, the module does not load, | ||||||||||
| 445 | or the class fails the isa test. | ||||||||||
| 446 | |||||||||||
| 447 | =head1 TO DO | ||||||||||
| 448 | |||||||||||
| 449 | - Add _CAN to help resolve the UNIVERSAL::can debacle | ||||||||||
| 450 | |||||||||||
| 451 | - Implement an assertion-like version of this module, that dies on | ||||||||||
| 452 | error. | ||||||||||
| 453 | |||||||||||
| 454 | - Implement a Test:: version of this module, for use in testing | ||||||||||
| 455 | |||||||||||
| 456 | =head1 SUPPORT | ||||||||||
| 457 | |||||||||||
| 458 | Bugs should be reported via the CPAN bug tracker at | ||||||||||
| 459 | |||||||||||
| 460 | L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Params-Util> | ||||||||||
| 461 | |||||||||||
| 462 | =head1 AUTHOR | ||||||||||
| 463 | |||||||||||
| 464 | Adam Kennedy E<lt>adamk AT cpan.orgE<gt> | ||||||||||
| 465 | |||||||||||
| 466 | Jens Rehsack E<lt>rehsack AT cpan.orgE<gt> | ||||||||||
| 467 | |||||||||||
| 468 | =head1 SEE ALSO | ||||||||||
| 469 | |||||||||||
| 470 | L<Params::Validate> | ||||||||||
| 471 | |||||||||||
| 472 | =head1 COPYRIGHT | ||||||||||
| 473 | |||||||||||
| 474 | Copyright 2005 - 2012 Adam Kennedy. | ||||||||||
| 475 | |||||||||||
| 476 | Copyright 2020 - 2020 Jens Rehsack. | ||||||||||
| 477 | |||||||||||
| 478 | This program is free software; you can redistribute | ||||||||||
| 479 | it and/or modify it under the same terms as Perl itself. | ||||||||||
| 480 | |||||||||||
| 481 | The full text of the license can be found in the | ||||||||||
| 482 | LICENSE file included with this module. | ||||||||||
| 483 | |||||||||||
| 484 | =cut | ||||||||||
| 485 | |||||||||||
| 486 | 18 | 1; | |||||||||