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