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,
54 and provides a convenient way to test to see if a value is a normal
55 non-false string of non-zero length.
56 Note that this will NOT do anything magic to deal with the special '0'
58 false negative case, but will return it.
59 # '0' not considered valid data
61 my $name = _STRING(shift) or die "Bad name";
62 # '0' is considered valid data
64 my $string = _STRING($_[0]) ? shift : die "Bad string";
65 Please also note that this function expects a normal string. It does
67 not support overloading or other magic techniques to get a string.
68 Returns the string as a conveince if it is a valid string, or "undef"
70 if not.
71 _IDENTIFIER $string
73 The "_IDENTIFIER" function is intended to be imported into your pack‐
75 age, and provides a convenient way to test to see if a value is a
76 string that is a valid Perl identifier.
77 Returns the string as a convenience if it is a valid identifier, or
79 "undef" if not.
80 _CLASS $string
82 The "_CLASS" function is intended to be imported into your package, and
84 provides a convenient way to test to see if a value is a string that is
85 a valid Perl class.
86 This function only checks that the format is valid, not that the class
88 is actually loaded. It also assumes "normalised" form, and does not
89 accept class names such as "::Foo" or "D'Oh".
90 Returns the string as a convenience if it is a valid class name, or
92 "undef" if not.
93 _CLASSISA $string, $class
95 The "_CLASSISA" function is intended to be imported into your package,
97 and provides a convenient way to test to see if a value is a string
98 that is a particularly class, or a subclass of it.
99 This function checks that the format is valid and calls the ->isa
101 method on the class name. It does not check that the class is actually
102 loaded.
103 It also assumes "normalised" form, and does not accept class names such
105 as "::Foo" or "D'Oh".
106 Returns the string as a convenience if it is a valid class name, or
108 "undef" if not.
109 _SUBCLASS $string, $class
111 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 _POSINT $integer
127 The "_POSINT" function is intended to be imported into your package,
129 and provides a convenient way to test to see if a value is a positive
130 integer (of any length).
131 Returns the value as a convience, or "undef" if the value is not a pos‐
133 itive integer.
134 The name itself is derived from the XML schema constraint of the same
136 name.
137 _NONNEGINT $integer
139 The "_NONNEGINT" function is intended to be imported into your package,
141 and provides a convenient way to test to see if a value is a non-nega‐
142 tive integer (of any length). That is, a positive integer, or zero.
143 Returns the value as a convience, or "undef" if the value is not a non-
145 negative integer.
146 As with other tests that may return false values, care should be taken
148 to test via "defined" in boolean validy contexts.
149 unless ( defined _NONNEGINT($value) ) {
151 die "Invalid value";
152 }
153 The name itself is derived from the XML schema constraint of the same
155 name.
156 _SCALAR \$scalar
158 The "_SCALAR" function is intended to be imported into your package,
160 and provides a convenient way to test for a raw and unblessed "SCALAR"
161 reference, with content of non-zero length.
162 For a version that allows zero length "SCALAR" references, see the
164 "_SCALAR0" function.
165 Returns the "SCALAR" reference itself as a convenience, or "undef" if
167 the value provided is not a "SCALAR" reference.
168 _SCALAR0 \$scalar
170 The "_SCALAR0" function is intended to be imported into your package,
172 and provides a convenient way to test for a raw and unblessed "SCALAR0"
173 reference, allowing content of zero-length.
174 For a simpler "give me some content" version that requires non-zero
176 length, "_SCALAR" function.
177 Returns the "SCALAR" reference itself as a convenience, or "undef" if
179 the value provided is not a "SCALAR" reference.
180 _ARRAY $value
182 The "_ARRAY" function is intended to be imported into your package, and
184 provides a convenient way to test for a raw and unblessed "ARRAY" ref‐
185 erence containing at least one element of any kind.
186 For a more basic form that allows zero length ARRAY references, see the
188 "_ARRAY0" function.
189 Returns the "ARRAY" reference itself as a convenience, or "undef" if
191 the value provided is not an "ARRAY" reference.
192 _ARRAY0 $value
194 The "_ARRAY0" function is intended to be imported into your package,
196 and provides a convenient way to test for a raw and unblessed "ARRAY"
197 reference, allowing "ARRAY" references that contain no elements.
198 For a more basic "An array of something" form that also requires at
200 least one element, see the "_ARRAY" function.
201 Returns the "ARRAY" reference itself as a convenience, or "undef" if
203 the value provided is not an "ARRAY" reference.
204 _ARRAYLIKE $value
206 The "_ARRAYLIKE" function tests whether a given scalar value can
208 respond to array dereferencing. If it can, the value is returned. If
209 it cannot, "_ARRAYLIKE" returns "undef".
210 _HASH $value
212 The "_HASH" function is intended to be imported into your package, and
214 provides a convenient way to test for a raw and unblessed "HASH" refer‐
215 ence with at least one entry.
216 For a version of this function that allows the "HASH" to be empty, see
218 the "_HASH0" function.
219 Returns the "HASH" reference itself as a convenience, or "undef" if the
221 value provided is not an "HASH" reference.
222 _HASH0 $value
224 The "_HASH0" function is intended to be imported into your package, and
226 provides a convenient way to test for a raw and unblessed "HASH" refer‐
227 ence, regardless of the "HASH" content.
228 For a simpler "A hash of something" version that requires at least one
230 element, see the "_HASH" function.
231 Returns the "HASH" reference itself as a convenience, or "undef" if the
233 value provided is not an "HASH" reference.
234 _HASHLIKE $value
236 The "_HASHLIKE" function tests whether a given scalar value can respond
238 to hash dereferencing. If it can, the value is returned. If it can‐
239 not, "_HASHLIKE" returns "undef".
240 _CODE $value
242 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" refer‐
245 ence.
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",
253 which checks for an explicit "CODE" reference, the "_CODELIKE" function
254 also includes things that act like them, such as blessed objects that
255 overload '&{}'.
256 Please note that in the case of objects overloaded with '&{}', you will
258 almost always end up also testing it in 'bool' context at some stage.
259 For example:
261 sub foo {
263 my $coed1 = _CODELIKE(shift) or die "No code param provided";
264 my $code2 = _CODELIKE(shift);
265 if ( $code2 ) {
266 print "Got optional second code param";
267 }
268 }
269 As such, you will most likely always want to make sure your class has
271 at least the following to allow it to evaluate to true in boolean con‐
272 text.
273 # Always evaluate to true in boolean context
275 use overload 'bool' => sub () { 1 };
276 Returns the callable value as a convenience, or "undef" if the value
278 provided is not callable.
279 Note - This function was formerly known as _CALLABLE but has been
281 renamed for greater symmetry with the other _XXXXLIKE functions.
282 The use of _CALLABLE has been deprecated. It will continue to work, but
284 with a warning, until end-2006, then will be removed.
285 I apologise for any inconvenience caused.
287 _INVOCANT $value
289 This routine tests whether the given value is a valid method invocant.
291 This can be either an instance of an object, or a class name.
292 If so, the value itself is returned. Otherwise, "_INVOCANT" returns
294 "undef".
295 _INSTANCE $object, $class
297 The "_INSTANCE" function is intended to be imported into your package,
299 and provides a convenient way to test for an object of a particular
300 class in a strictly correct manner.
301 Returns the object itself as a convenience, or "undef" if the value
303 provided is not an object of that type.
304 _SET \@array, $class
306 The "_SET" function is intended to be imported into your package, and
308 provides a convenient way to test for set of at least one object of a
309 particular class in a strictly correct manner.
310 The set is provided as a reference to an "ARRAY" of objects of the
312 class provided.
313 For an alternative function that allows zero-length sets, see the
315 "_SET0" function.
316 Returns the "ARRAY" reference itself as a convenience, or "undef" if
318 the value provided is not a set of that class.
319 _SET0 \@array, $class
321 The "_SET0" function is intended to be imported into your package, and
323 provides a convenient way to test for a set of objects of a particular
324 class in a strictly correct manner, allowing for zero objects.
325 The set is provided as a reference to an "ARRAY" of objects of the
327 class provided.
328 For an alternative function that requires at least one object, see the
330 "_SET" function.
331 Returns the "ARRAY" reference itself as a convenience, or "undef" if
333 the value provided is not a set of that class.
334 _HANDLE
336 EXPERIMENTAL: SUBJECT TO CHANGE OR POSSIBLE REMOVAL
338 The "_HANDLE" function is intended to be imported into your package,
340 and provides a convenient way to test whether or not a single scalar
341 value is a file handle.
342 Unfortunately, in Perl the definition of a file handle can be a little
344 bit fuzzy, so this function is likely to be somewhat imperfect (at
345 first anyway).
346 That said, it is implement as well or better than the other file handle
348 detectors in existance (and we stole from the best of them).
349 _DRIVER $string
351 sub foo {
353 my $class = _DRIVER(shift, 'My::Driver::Base') or die "Bad driver";
354 ...
355 }
356 EXPERIMENTAL: SUBJECT TO CHANGE OR POSSIBLE REMOVAL
358 The "_DRIVER" function is intended to be imported into your package,
360 and provides a convenient way to load and validate a driver class.
361 The most common pattern when taking a driver class as a parameter is to
363 check that the name is a class (i.e. check against _CLASS) and then to
364 load the class (if it exists) and then ensure that the class returns
365 true for the isa method on some base driver name.
366 Return the value as a convenience, or "undef" if the value is not a
368 class name, the module does not exist, the module does not load, or the
369 class fails the isa test.
370
372 - Add _CAN to help resolve the UNIVERSAL::can debacle
373 - More comprehensive tests for _SET and _SET0
375 - Would be nice if someone would re-implement in XS for me? (done'ish)
377 - Would be even nicer if someone would demonstrate how the hell to
379 build a Module::Install dist of the ::Util dual Perl/XS type. :/
380 - Implement an assertion-like version of this module, that dies on
382 error.
383 - Implement a Test:: version of this module, for use in testing
385
387 Bugs should be reported via the CPAN bug tracker at
388 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Params-Util>
390 For other issues, contact the author.
392
394 Adam Kennedy <adamk@cpan.org>
395
397 Params::Validate, <http://ali.as/>
398
400 Copyright 2005, 2006 Adam Kennedy.
401 This program is free software; you can redistribute it and/or modify it
403 under the same terms as Perl itself.
404 The full text of the license can be found in the LICENSE file included
406 with this module.
407perl v5.8.8 2007-11-14 Params::Util(3)