| 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 | 20 | ▶ | use 5.00503; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 59 | 20 | ▶ | use strict; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 60 | 20 | ▶ | use warnings; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 61 | 20 | ▶ | use parent qw{Exporter XSLoader}; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 62 | |||||||||||
| 63 | 20 | ▶ | use Params::Util::PP qw(); | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 64 | |||||||||||
| 65 | 20 | our $VERSION = '1.105_001'; | |||||||||
| 66 | |||||||||||
| 67 | 20 | ▶ | local $ENV{PERL_DL_NONLAZY} = 0 if $ENV{PERL_DL_NONLAZY}; | ||||||||
|
Branch: 1 branch
| |||||||||||
| 68 | 20 | ▶ | XSLoader::load("Params::Util", $VERSION) unless $ENV{PERL_PARAMS_UTIL_PP}; | ||||||||
|
Branch: 1 branch
| |||||||||||
| 69 | |||||||||||
| 70 | 20 | our @EXPORT_OK = qw{ | |||||||||
| 71 | _STRING _IDENTIFIER | ||||||||||
| 72 | _CLASS _CLASSISA _CLASSCAN _SUBCLASS _DRIVER _CLASSDOES | ||||||||||
| 73 | _NUMBER _POSINT _NONNEGINT | ||||||||||
| 74 | _SCALAR _SCALAR0 | ||||||||||
| 75 | _ARRAY _ARRAY0 _ARRAYLIKE | ||||||||||
| 76 | _HASH _HASH0 _HASHLIKE | ||||||||||
| 77 | _CODE _CODELIKE | ||||||||||
| 78 | _INVOCANT _INVOCANTCAN | ||||||||||
| 79 | _REGEX _INSTANCE _INSTANCEDOES _INSTANCECAN | ||||||||||
| 80 | _SET _SET0 | ||||||||||
| 81 | _HANDLE | ||||||||||
| 82 | }; | ||||||||||
| 83 | 20 | our %EXPORT_TAGS = (ALL => \@EXPORT_OK); | |||||||||
| 84 | |||||||||||
| 85 | ## no critic (TestingAndDebugging::ProhibitNoStrict) | ||||||||||
| 86 | 20 | ▶ | no strict "refs"; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 87 | 20 | ▶ | Params::Util->can($_) or *$_ = Params::Util::PP->can($_) for (@EXPORT_OK); | ||||||||
|
Branch: 1 branch
| |||||||||||
| 88 | 20 | ▶ | use strict "refs"; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 89 | |||||||||||
| 90 | ##################################################################### | ||||||||||
| 91 | # Param Checking Functions | ||||||||||
| 92 | |||||||||||
| 93 | =pod | ||||||||||
| 94 | |||||||||||
| 95 | =head2 _STRING $string | ||||||||||
| 96 | |||||||||||
| 97 | The C<_STRING> function is intended to be imported into your | ||||||||||
| 98 | package, and provides a convenient way to test to see if a value is | ||||||||||
| 99 | a normal non-false string of non-zero length. | ||||||||||
| 100 | |||||||||||
| 101 | Note that this will NOT do anything magic to deal with the special | ||||||||||
| 102 | C<'0'> false negative case, but will return it. | ||||||||||
| 103 | |||||||||||
| 104 | # '0' not considered valid data | ||||||||||
| 105 | my $name = _STRING(shift) or die "Bad name"; | ||||||||||
| 106 | |||||||||||
| 107 | # '0' is considered valid data | ||||||||||
| 108 | my $string = _STRING($_[0]) ? shift : die "Bad string"; | ||||||||||
| 109 | |||||||||||
| 110 | Please also note that this function expects a normal string. It does | ||||||||||
| 111 | not support overloading or other magic techniques to get a string. | ||||||||||
| 112 | |||||||||||
| 113 | Returns the string as a convenience if it is a valid string, or | ||||||||||
| 114 | C<undef> if not. | ||||||||||
| 115 | |||||||||||
| 116 | =head2 _IDENTIFIER $string | ||||||||||
| 117 | |||||||||||
| 118 | The C<_IDENTIFIER> function is intended to be imported into your | ||||||||||
| 119 | package, and provides a convenient way to test to see if a value is | ||||||||||
| 120 | a string that is a valid Perl identifier. | ||||||||||
| 121 | |||||||||||
| 122 | Returns the string as a convenience if it is a valid identifier, or | ||||||||||
| 123 | C<undef> if not. | ||||||||||
| 124 | |||||||||||
| 125 | =head2 _CLASS $string | ||||||||||
| 126 | |||||||||||
| 127 | The C<_CLASS> function is intended to be imported into your | ||||||||||
| 128 | package, and provides a convenient way to test to see if a value is | ||||||||||
| 129 | a string that is a valid Perl class. | ||||||||||
| 130 | |||||||||||
| 131 | This function only checks that the format is valid, not that the | ||||||||||
| 132 | class is actually loaded. It also assumes "normalized" form, and does | ||||||||||
| 133 | not accept class names such as C<::Foo> or C<D'Oh>. | ||||||||||
| 134 | |||||||||||
| 135 | Returns the string as a convenience if it is a valid class name, or | ||||||||||
| 136 | C<undef> if not. | ||||||||||
| 137 | |||||||||||
| 138 | =head2 _CLASSISA $string, $class | ||||||||||
| 139 | |||||||||||
| 140 | The C<_CLASSISA> function is intended to be imported into your | ||||||||||
| 141 | package, and provides a convenient way to test to see if a value is | ||||||||||
| 142 | a string that is a particularly class, or a subclass of it. | ||||||||||
| 143 | |||||||||||
| 144 | This function checks that the format is valid and calls the -E<gt>isa | ||||||||||
| 145 | method on the class name. It does not check that the class is actually | ||||||||||
| 146 | loaded. | ||||||||||
| 147 | |||||||||||
| 148 | It also assumes "normalized" form, and does | ||||||||||
| 149 | not accept class names such as C<::Foo> or C<D'Oh>. | ||||||||||
| 150 | |||||||||||
| 151 | Returns the string as a convenience if it is a valid class name, or | ||||||||||
| 152 | C<undef> if not. | ||||||||||
| 153 | |||||||||||
| 154 | =head2 _CLASSDOES $string, $role | ||||||||||
| 155 | |||||||||||
| 156 | This routine behaves exactly like C<L</_CLASSISA>>, but checks with C<< ->DOES | ||||||||||
| 157 | >> rather than C<< ->isa >>. This is probably only a good idea to use on Perl | ||||||||||
| 158 | 5.10 or later, when L<UNIVERSAL::DOES|UNIVERSAL::DOES/DOES> has been | ||||||||||
| 159 | implemented. | ||||||||||
| 160 | |||||||||||
| 161 | =head2 _CLASSCAN $string, $method | ||||||||||
| 162 | |||||||||||
| 163 | The C<_CLASSCAN> function tests whether a value is a valid class name that | ||||||||||
| 164 | provides a particular method via C<< ->can >>. | ||||||||||
| 165 | |||||||||||
| 166 | This avoids calling C<UNIVERSAL::can> as a function, which is considered | ||||||||||
| 167 | problematic because it bypasses any overridden C<can> method. | ||||||||||
| 168 | |||||||||||
| 169 | Returns the string as a convenience if it is a valid class name that provides | ||||||||||
| 170 | the method, or C<undef> if not. | ||||||||||
| 171 | |||||||||||
| 172 | =head2 _SUBCLASS $string, $class | ||||||||||
| 173 | |||||||||||
| 174 | The C<_SUBCLASS> function is intended to be imported into your | ||||||||||
| 175 | package, and provides a convenient way to test to see if a value is | ||||||||||
| 176 | a string that is a subclass of a specified class. | ||||||||||
| 177 | |||||||||||
| 178 | This function checks that the format is valid and calls the -E<gt>isa | ||||||||||
| 179 | method on the class name. It does not check that the class is actually | ||||||||||
| 180 | loaded. | ||||||||||
| 181 | |||||||||||
| 182 | It also assumes "normalized" form, and does | ||||||||||
| 183 | not accept class names such as C<::Foo> or C<D'Oh>. | ||||||||||
| 184 | |||||||||||
| 185 | Returns the string as a convenience if it is a valid class name, or | ||||||||||
| 186 | C<undef> if not. | ||||||||||
| 187 | |||||||||||
| 188 | =head2 _NUMBER $scalar | ||||||||||
| 189 | |||||||||||
| 190 | The C<_NUMBER> 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 number. That is, it is defined and perl thinks it's a number. | ||||||||||
| 193 | |||||||||||
| 194 | This function is basically a Params::Util-style wrapper around the | ||||||||||
| 195 | L<Scalar::Util> C<looks_like_number> function. | ||||||||||
| 196 | |||||||||||
| 197 | Returns the value as a convenience, or C<undef> if the value is not a | ||||||||||
| 198 | number. | ||||||||||
| 199 | |||||||||||
| 200 | =head2 _POSINT $integer | ||||||||||
| 201 | |||||||||||
| 202 | The C<_POSINT> 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 positive integer (of any length). | ||||||||||
| 205 | |||||||||||
| 206 | Returns the value as a convenience, or C<undef> if the value is not a | ||||||||||
| 207 | positive integer. | ||||||||||
| 208 | |||||||||||
| 209 | The name itself is derived from the XML schema constraint of the same | ||||||||||
| 210 | name. | ||||||||||
| 211 | |||||||||||
| 212 | =head2 _NONNEGINT $integer | ||||||||||
| 213 | |||||||||||
| 214 | The C<_NONNEGINT> function is intended to be imported into your | ||||||||||
| 215 | package, and provides a convenient way to test to see if a value is | ||||||||||
| 216 | a non-negative integer (of any length). That is, a positive integer, | ||||||||||
| 217 | or zero. | ||||||||||
| 218 | |||||||||||
| 219 | Returns the value as a convenience, or C<undef> if the value is not a | ||||||||||
| 220 | non-negative integer. | ||||||||||
| 221 | |||||||||||
| 222 | As with other tests that may return false values, care should be taken | ||||||||||
| 223 | to test via "defined" in boolean validly contexts. | ||||||||||
| 224 | |||||||||||
| 225 | unless ( defined _NONNEGINT($value) ) { | ||||||||||
| 226 | die "Invalid value"; | ||||||||||
| 227 | } | ||||||||||
| 228 | |||||||||||
| 229 | The name itself is derived from the XML schema constraint of the same | ||||||||||
| 230 | name. | ||||||||||
| 231 | |||||||||||
| 232 | =head2 _SCALAR \$scalar | ||||||||||
| 233 | |||||||||||
| 234 | The C<_SCALAR> function is intended to be imported into your package, | ||||||||||
| 235 | and provides a convenient way to test for a raw and unblessed | ||||||||||
| 236 | C<SCALAR> reference, with content of non-zero length. | ||||||||||
| 237 | |||||||||||
| 238 | For a version that allows zero length C<SCALAR> references, see | ||||||||||
| 239 | the C<_SCALAR0> 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 _SCALAR0 \$scalar | ||||||||||
| 245 | |||||||||||
| 246 | The C<_SCALAR0> function is intended to be imported into your package, | ||||||||||
| 247 | and provides a convenient way to test for a raw and unblessed | ||||||||||
| 248 | C<SCALAR0> reference, allowing content of zero-length. | ||||||||||
| 249 | |||||||||||
| 250 | For a simpler "give me some content" version that requires non-zero | ||||||||||
| 251 | length, C<_SCALAR> function. | ||||||||||
| 252 | |||||||||||
| 253 | Returns the C<SCALAR> reference itself as a convenience, or C<undef> | ||||||||||
| 254 | if the value provided is not a C<SCALAR> reference. | ||||||||||
| 255 | |||||||||||
| 256 | =head2 _ARRAY $value | ||||||||||
| 257 | |||||||||||
| 258 | The C<_ARRAY> 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 containing B<at least> one element of any kind. | ||||||||||
| 261 | |||||||||||
| 262 | For a more basic form that allows zero length ARRAY references, see | ||||||||||
| 263 | the C<_ARRAY0> function. | ||||||||||
| 264 | |||||||||||
| 265 | Returns the C<ARRAY> reference itself as a convenience, or C<undef> | ||||||||||
| 266 | if the value provided is not an C<ARRAY> reference. | ||||||||||
| 267 | |||||||||||
| 268 | =head2 _ARRAY0 $value | ||||||||||
| 269 | |||||||||||
| 270 | The C<_ARRAY0> function is intended to be imported into your package, | ||||||||||
| 271 | and provides a convenient way to test for a raw and unblessed | ||||||||||
| 272 | C<ARRAY> reference, allowing C<ARRAY> references that contain no | ||||||||||
| 273 | elements. | ||||||||||
| 274 | |||||||||||
| 275 | For a more basic "An array of something" form that also requires at | ||||||||||
| 276 | least one element, see the C<_ARRAY> function. | ||||||||||
| 277 | |||||||||||
| 278 | Returns the C<ARRAY> reference itself as a convenience, or C<undef> | ||||||||||
| 279 | if the value provided is not an C<ARRAY> reference. | ||||||||||
| 280 | |||||||||||
| 281 | =head2 _ARRAYLIKE $value | ||||||||||
| 282 | |||||||||||
| 283 | The C<_ARRAYLIKE> function tests whether a given scalar value can respond to | ||||||||||
| 284 | array dereferencing. If it can, the value is returned. If it cannot, | ||||||||||
| 285 | C<_ARRAYLIKE> returns C<undef>. | ||||||||||
| 286 | |||||||||||
| 287 | =head2 _HASH $value | ||||||||||
| 288 | |||||||||||
| 289 | The C<_HASH> 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 with at least one entry. | ||||||||||
| 292 | |||||||||||
| 293 | For a version of this function that allows the C<HASH> to be empty, | ||||||||||
| 294 | see the C<_HASH0> 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 _HASH0 $value | ||||||||||
| 300 | |||||||||||
| 301 | The C<_HASH0> function is intended to be imported into your package, | ||||||||||
| 302 | and provides a convenient way to test for a raw and unblessed | ||||||||||
| 303 | C<HASH> reference, regardless of the C<HASH> content. | ||||||||||
| 304 | |||||||||||
| 305 | For a simpler "A hash of something" version that requires at least one | ||||||||||
| 306 | element, see the C<_HASH> function. | ||||||||||
| 307 | |||||||||||
| 308 | Returns the C<HASH> reference itself as a convenience, or C<undef> | ||||||||||
| 309 | if the value provided is not an C<HASH> reference. | ||||||||||
| 310 | |||||||||||
| 311 | =head2 _HASHLIKE $value | ||||||||||
| 312 | |||||||||||
| 313 | The C<_HASHLIKE> function tests whether a given scalar value can respond to | ||||||||||
| 314 | hash dereferencing. If it can, the value is returned. If it cannot, | ||||||||||
| 315 | C<_HASHLIKE> returns C<undef>. | ||||||||||
| 316 | |||||||||||
| 317 | =head2 _CODE $value | ||||||||||
| 318 | |||||||||||
| 319 | The C<_CODE> function is intended to be imported into your package, | ||||||||||
| 320 | and provides a convenient way to test for a raw and unblessed | ||||||||||
| 321 | C<CODE> reference. | ||||||||||
| 322 | |||||||||||
| 323 | Returns the C<CODE> reference itself as a convenience, or C<undef> | ||||||||||
| 324 | if the value provided is not an C<CODE> reference. | ||||||||||
| 325 | |||||||||||
| 326 | =head2 _CODELIKE $value | ||||||||||
| 327 | |||||||||||
| 328 | The C<_CODELIKE> is the more generic version of C<_CODE>. Unlike C<_CODE>, | ||||||||||
| 329 | which checks for an explicit C<CODE> reference, the C<_CODELIKE> function | ||||||||||
| 330 | also includes things that act like them, such as blessed objects that | ||||||||||
| 331 | overload C<'&{}'>. | ||||||||||
| 332 | |||||||||||
| 333 | Please note that in the case of objects overloaded with '&{}', you will | ||||||||||
| 334 | almost always end up also testing it in 'bool' context at some stage. | ||||||||||
| 335 | |||||||||||
| 336 | For example: | ||||||||||
| 337 | |||||||||||
| 338 | sub foo { | ||||||||||
| 339 | my $code1 = _CODELIKE(shift) or die "No code param provided"; | ||||||||||
| 340 | my $code2 = _CODELIKE(shift); | ||||||||||
| 341 | if ( $code2 ) { | ||||||||||
| 342 | print "Got optional second code param"; | ||||||||||
| 343 | } | ||||||||||
| 344 | } | ||||||||||
| 345 | |||||||||||
| 346 | As such, you will most likely always want to make sure your class has | ||||||||||
| 347 | at least the following to allow it to evaluate to true in boolean | ||||||||||
| 348 | context. | ||||||||||
| 349 | |||||||||||
| 350 | # Always evaluate to true in boolean context | ||||||||||
| 351 | use overload 'bool' => sub () { 1 }; | ||||||||||
| 352 | |||||||||||
| 353 | Returns the callable value as a convenience, or C<undef> if the | ||||||||||
| 354 | value provided is not callable. | ||||||||||
| 355 | |||||||||||
| 356 | Note - This function was formerly known as _CALLABLE but has been renamed | ||||||||||
| 357 | for greater symmetry with the other _XXXXLIKE functions. | ||||||||||
| 358 | |||||||||||
| 359 | The use of _CALLABLE has been deprecated. It will continue to work, but | ||||||||||
| 360 | with a warning, until end-2006, then will be removed. | ||||||||||
| 361 | |||||||||||
| 362 | I apologize for any inconvenience caused. | ||||||||||
| 363 | |||||||||||
| 364 | =head2 _INVOCANT $value | ||||||||||
| 365 | |||||||||||
| 366 | This routine tests whether the given value is a valid method invocant. | ||||||||||
| 367 | This can be either an instance of an object, or a class name. | ||||||||||
| 368 | |||||||||||
| 369 | If so, the value itself is returned. Otherwise, C<_INVOCANT> | ||||||||||
| 370 | returns C<undef>. | ||||||||||
| 371 | |||||||||||
| 372 | =head2 _INSTANCE $object, $class | ||||||||||
| 373 | |||||||||||
| 374 | The C<_INSTANCE> function is intended to be imported into your package, | ||||||||||
| 375 | and provides a convenient way to test for an object of a particular class | ||||||||||
| 376 | in a strictly correct manner. | ||||||||||
| 377 | |||||||||||
| 378 | Returns the object itself as a convenience, or C<undef> if the value | ||||||||||
| 379 | provided is not an object of that type. | ||||||||||
| 380 | |||||||||||
| 381 | =head2 _INSTANCEDOES $object, $role | ||||||||||
| 382 | |||||||||||
| 383 | This routine behaves exactly like C<L</_INSTANCE>>, but checks with C<< ->DOES | ||||||||||
| 384 | >> rather than C<< ->isa >>. This is probably only a good idea to use on Perl | ||||||||||
| 385 | 5.10 or later, when L<UNIVERSAL::DOES|UNIVERSAL::DOES/DOES> has been | ||||||||||
| 386 | implemented. | ||||||||||
| 387 | |||||||||||
| 388 | =head2 _INSTANCECAN $object, $method | ||||||||||
| 389 | |||||||||||
| 390 | This routine behaves exactly like C<L</_INSTANCE>>, but checks with C<< ->can | ||||||||||
| 391 | >> rather than C<< ->isa >>. Returns the object as a convenience if it is | ||||||||||
| 392 | blessed and provides the specified method, or C<undef> if not. | ||||||||||
| 393 | |||||||||||
| 394 | =head2 _INVOCANTCAN $value, $method | ||||||||||
| 395 | |||||||||||
| 396 | Tests whether the given value is a valid method invocant (class name or | ||||||||||
| 397 | blessed object) that provides a particular method via C<< ->can >>. | ||||||||||
| 398 | |||||||||||
| 399 | Returns the value itself as a convenience, or C<undef> if the value is not | ||||||||||
| 400 | a valid invocant or does not provide the method. | ||||||||||
| 401 | |||||||||||
| 402 | =head2 _REGEX $value | ||||||||||
| 403 | |||||||||||
| 404 | The C<_REGEX> function is intended to be imported into your package, | ||||||||||
| 405 | and provides a convenient way to test for a regular expression. | ||||||||||
| 406 | |||||||||||
| 407 | Returns the value itself as a convenience, or C<undef> if the value | ||||||||||
| 408 | provided is not a regular expression. | ||||||||||
| 409 | |||||||||||
| 410 | =head2 _SET \@array, $class | ||||||||||
| 411 | |||||||||||
| 412 | The C<_SET> function is intended to be imported into your package, | ||||||||||
| 413 | and provides a convenient way to test for set of at least one object of | ||||||||||
| 414 | a particular class in a strictly correct manner. | ||||||||||
| 415 | |||||||||||
| 416 | The set is provided as a reference to an C<ARRAY> of objects of the | ||||||||||
| 417 | class provided. | ||||||||||
| 418 | |||||||||||
| 419 | For an alternative function that allows zero-length sets, see the | ||||||||||
| 420 | C<_SET0> function. | ||||||||||
| 421 | |||||||||||
| 422 | Returns the C<ARRAY> reference itself as a convenience, or C<undef> if | ||||||||||
| 423 | the value provided is not a set of that class. | ||||||||||
| 424 | |||||||||||
| 425 | =head2 _SET0 \@array, $class | ||||||||||
| 426 | |||||||||||
| 427 | The C<_SET0> function is intended to be imported into your package, | ||||||||||
| 428 | and provides a convenient way to test for a set of objects of a | ||||||||||
| 429 | particular class in a strictly correct manner, allowing for zero objects. | ||||||||||
| 430 | |||||||||||
| 431 | The set is provided as a reference to an C<ARRAY> of objects of the | ||||||||||
| 432 | class provided. | ||||||||||
| 433 | |||||||||||
| 434 | For an alternative function that requires at least one object, see the | ||||||||||
| 435 | C<_SET> function. | ||||||||||
| 436 | |||||||||||
| 437 | Returns the C<ARRAY> reference itself as a convenience, or C<undef> if | ||||||||||
| 438 | the value provided is not a set of that class. | ||||||||||
| 439 | |||||||||||
| 440 | =head2 _HANDLE | ||||||||||
| 441 | |||||||||||
| 442 | The C<_HANDLE> function is intended to be imported into your package, | ||||||||||
| 443 | and provides a convenient way to test whether or not a single scalar | ||||||||||
| 444 | value is a file handle. | ||||||||||
| 445 | |||||||||||
| 446 | Unfortunately, in Perl the definition of a file handle can be a little | ||||||||||
| 447 | bit fuzzy, so this function is likely to be somewhat imperfect (at first | ||||||||||
| 448 | anyway). | ||||||||||
| 449 | |||||||||||
| 450 | That said, it is implement as well or better than the other file handle | ||||||||||
| 451 | detectors in existence (and we stole from the best of them). | ||||||||||
| 452 | |||||||||||
| 453 | =head2 _DRIVER $string | ||||||||||
| 454 | |||||||||||
| 455 | sub foo { | ||||||||||
| 456 | my $class = _DRIVER(shift, 'My::Driver::Base') or die "Bad driver"; | ||||||||||
| 457 | ... | ||||||||||
| 458 | } | ||||||||||
| 459 | |||||||||||
| 460 | The C<_DRIVER> function is intended to be imported into your | ||||||||||
| 461 | package, and provides a convenient way to load and validate | ||||||||||
| 462 | a driver class. | ||||||||||
| 463 | |||||||||||
| 464 | The most common pattern when taking a driver class as a parameter | ||||||||||
| 465 | is to check that the name is a class (i.e. check against _CLASS) | ||||||||||
| 466 | and then to load the class (if it exists) and then ensure that | ||||||||||
| 467 | the class returns true for the isa method on some base driver name. | ||||||||||
| 468 | |||||||||||
| 469 | Return the value as a convenience, or C<undef> if the value is not | ||||||||||
| 470 | a class name, the module does not exist, the module does not load, | ||||||||||
| 471 | or the class fails the isa test. | ||||||||||
| 472 | |||||||||||
| 473 | =head1 TO DO | ||||||||||
| 474 | |||||||||||
| 475 | - Implement an assertion-like version of this module, that dies on | ||||||||||
| 476 | error. See L<Params::Util::ADR-003> for design considerations. | ||||||||||
| 477 | |||||||||||
| 478 | - Implement a Test:: version of this module, for use in testing. | ||||||||||
| 479 | See L<Params::Util::ADR-004> for the rationale to ship it as a | ||||||||||
| 480 | separate distribution. | ||||||||||
| 481 | |||||||||||
| 482 | =head1 SUPPORT | ||||||||||
| 483 | |||||||||||
| 484 | Bugs and feature requests should be reported via GitHub Issues at | ||||||||||
| 485 | |||||||||||
| 486 | L<https://github.com/perl5-utils/Params-Util/issues> | ||||||||||
| 487 | |||||||||||
| 488 | The source repository is at | ||||||||||
| 489 | |||||||||||
| 490 | L<https://github.com/perl5-utils/Params-Util> | ||||||||||
| 491 | |||||||||||
| 492 | For historical bug reports, see the CPAN RT queue at | ||||||||||
| 493 | |||||||||||
| 494 | L<https://rt.cpan.org/Dist/Display.html?Name=Params-Util> | ||||||||||
| 495 | |||||||||||
| 496 | =head1 AUTHOR | ||||||||||
| 497 | |||||||||||
| 498 | Adam Kennedy E<lt>adamk AT cpan.orgE<gt> | ||||||||||
| 499 | |||||||||||
| 500 | Jens Rehsack E<lt>rehsack AT cpan.orgE<gt> | ||||||||||
| 501 | |||||||||||
| 502 | =head1 SEE ALSO | ||||||||||
| 503 | |||||||||||
| 504 | L<Params::Validate> | ||||||||||
| 505 | |||||||||||
| 506 | =head1 COPYRIGHT | ||||||||||
| 507 | |||||||||||
| 508 | Copyright 2005 - 2012 Adam Kennedy. | ||||||||||
| 509 | |||||||||||
| 510 | Copyright 2020 - 2026 Jens Rehsack. | ||||||||||
| 511 | |||||||||||
| 512 | This program is free software; you can redistribute | ||||||||||
| 513 | it and/or modify it under the same terms as Perl itself. | ||||||||||
| 514 | |||||||||||
| 515 | The full text of the license can be found in the | ||||||||||
| 516 | LICENSE file included with this module. | ||||||||||
| 517 | |||||||||||
| 518 | =cut | ||||||||||
| 519 | |||||||||||
| 520 | 20 | 1; | |||||||||