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