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 _SUBCLASS $string, $class
107 The "_SUBCLASS" function is intended to be imported into your package,
108 and provides a convenient way to test to see if a value is a string
109 that is a subclass of a specified class.
110 This function checks that the format is valid and calls the ->isa
112 method on the class name. It does not check that the class is actually
113 loaded.
114 It also assumes "normalised" form, and does not accept class names such
116 as "::Foo" or "D'Oh".
117 Returns the string as a convenience if it is a valid class name, or
119 "undef" if not.
120 _NUMBER $scalar
122 The "_NUMBER" function is intended to be imported into your package,
123 and provides a convenient way to test to see if a value is a number.
124 That is, it is defined and perl thinks it's a number.
125 This function is basically a Params::Util-style wrapper around the
127 Scalar::Util "looks_like_number" function.
128 Returns the value as a convience, or "undef" if the value is not a
130 number.
131 _POSINT $integer
133 The "_POSINT" function is intended to be imported into your package,
134 and provides a convenient way to test to see if a value is a positive
135 integer (of any length).
136 Returns the value as a convience, or "undef" if the value is not a
138 positive integer.
139 The name itself is derived from the XML schema constraint of the same
141 name.
142 _NONNEGINT $integer
144 The "_NONNEGINT" function is intended to be imported into your package,
145 and provides a convenient way to test to see if a value is a non-
146 negative integer (of any length). That is, a positive integer, or zero.
147 Returns the value as a convience, or "undef" if the value is not a non-
149 negative integer.
150 As with other tests that may return false values, care should be taken
152 to test via "defined" in boolean validy contexts.
153 unless ( defined _NONNEGINT($value) ) {
155 die "Invalid value";
156 }
157 The name itself is derived from the XML schema constraint of the same
159 name.
160 _SCALAR \$scalar
162 The "_SCALAR" function is intended to be imported into your package,
163 and provides a convenient way to test for a raw and unblessed "SCALAR"
164 reference, with content of non-zero length.
165 For a version that allows zero length "SCALAR" references, see the
167 "_SCALAR0" function.
168 Returns the "SCALAR" reference itself as a convenience, or "undef" if
170 the value provided is not a "SCALAR" reference.
171 _SCALAR0 \$scalar
173 The "_SCALAR0" function is intended to be imported into your package,
174 and provides a convenient way to test for a raw and unblessed "SCALAR0"
175 reference, allowing content of zero-length.
176 For a simpler "give me some content" version that requires non-zero
178 length, "_SCALAR" function.
179 Returns the "SCALAR" reference itself as a convenience, or "undef" if
181 the value provided is not a "SCALAR" reference.
182 _ARRAY $value
184 The "_ARRAY" function is intended to be imported into your package, and
185 provides a convenient way to test for a raw and unblessed "ARRAY"
186 reference containing at least one element of any kind.
187 For a more basic form that allows zero length ARRAY references, see the
189 "_ARRAY0" function.
190 Returns the "ARRAY" reference itself as a convenience, or "undef" if
192 the value provided is not an "ARRAY" reference.
193 _ARRAY0 $value
195 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
207 respond to array dereferencing. If it can, the value is returned. If
208 it cannot, "_ARRAYLIKE" returns "undef".
209 _HASH $value
211 The "_HASH" function is intended to be imported into your package, and
212 provides a convenient way to test for a raw and unblessed "HASH"
213 reference with at least one entry.
214 For a version of this function that allows the "HASH" to be empty, see
216 the "_HASH0" function.
217 Returns the "HASH" reference itself as a convenience, or "undef" if the
219 value provided is not an "HASH" reference.
220 _HASH0 $value
222 The "_HASH0" function is intended to be imported into your package, and
223 provides a convenient way to test for a raw and unblessed "HASH"
224 reference, regardless of the "HASH" content.
225 For a simpler "A hash of something" version that requires at least one
227 element, see the "_HASH" function.
228 Returns the "HASH" reference itself as a convenience, or "undef" if the
230 value provided is not an "HASH" reference.
231 _HASHLIKE $value
233 The "_HASHLIKE" function tests whether a given scalar value can respond
234 to hash dereferencing. If it can, the value is returned. If it
235 cannot, "_HASHLIKE" returns "undef".
236 _CODE $value
238 The "_CODE" function is intended to be imported into your package, and
239 provides a convenient way to test for a raw and unblessed "CODE"
240 reference.
241 Returns the "CODE" reference itself as a convenience, or "undef" if the
243 value provided is not an "CODE" reference.
244 _CODELIKE $value
246 The "_CODELIKE" is the more generic version of "_CODE". Unlike "_CODE",
247 which checks for an explicit "CODE" reference, the "_CODELIKE" function
248 also includes things that act like them, such as blessed objects that
249 overload '&{}'.
250 Please note that in the case of objects overloaded with '&{}', you will
252 almost always end up also testing it in 'bool' context at some stage.
253 For example:
255 sub foo {
257 my $code1 = _CODELIKE(shift) or die "No code param provided";
258 my $code2 = _CODELIKE(shift);
259 if ( $code2 ) {
260 print "Got optional second code param";
261 }
262 }
263 As such, you will most likely always want to make sure your class has
265 at least the following to allow it to evaluate to true in boolean
266 context.
267 # Always evaluate to true in boolean context
269 use overload 'bool' => sub () { 1 };
270 Returns the callable value as a convenience, or "undef" if the value
272 provided is not callable.
273 Note - This function was formerly known as _CALLABLE but has been
275 renamed for greater symmetry with the other _XXXXLIKE functions.
276 The use of _CALLABLE has been deprecated. It will continue to work, but
278 with a warning, until end-2006, then will be removed.
279 I apologise for any inconvenience caused.
281 _INVOCANT $value
283 This routine tests whether the given value is a valid method invocant.
284 This can be either an instance of an object, or a class name.
285 If so, the value itself is returned. Otherwise, "_INVOCANT" returns
287 "undef".
288 _INSTANCE $object, $class
290 The "_INSTANCE" function is intended to be imported into your package,
291 and provides a convenient way to test for an object of a particular
292 class in a strictly correct manner.
293 Returns the object itself as a convenience, or "undef" if the value
295 provided is not an object of that type.
296 _REGEX $value
298 The "_REGEX" function is intended to be imported into your package, and
299 provides a convenient way to test for a regular expression.
300 Returns the value itself as a convenience, or "undef" if the value
302 provided is not a regular expression.
303 _SET \@array, $class
305 The "_SET" function is intended to be imported into your package, and
306 provides a convenient way to test for set of at least one object of a
307 particular class in a strictly correct manner.
308 The set is provided as a reference to an "ARRAY" of objects of the
310 class provided.
311 For an alternative function that allows zero-length sets, see the
313 "_SET0" function.
314 Returns the "ARRAY" reference itself as a convenience, or "undef" if
316 the value provided is not a set of that class.
317 _SET0 \@array, $class
319 The "_SET0" function is intended to be imported into your package, and
320 provides a convenient way to test for a set of objects of a particular
321 class in a strictly correct manner, allowing for zero objects.
322 The set is provided as a reference to an "ARRAY" of objects of the
324 class provided.
325 For an alternative function that requires at least one object, see the
327 "_SET" function.
328 Returns the "ARRAY" reference itself as a convenience, or "undef" if
330 the value provided is not a set of that class.
331 _HANDLE
333 The "_HANDLE" function is intended to be imported into your package,
334 and provides a convenient way to test whether or not a single scalar
335 value is a file handle.
336 Unfortunately, in Perl the definition of a file handle can be a little
338 bit fuzzy, so this function is likely to be somewhat imperfect (at
339 first anyway).
340 That said, it is implement as well or better than the other file handle
342 detectors in existance (and we stole from the best of them).
343 _DRIVER $string
345 sub foo {
346 my $class = _DRIVER(shift, 'My::Driver::Base') or die "Bad driver";
347 ...
348 }
349 The "_DRIVER" function is intended to be imported into your package,
351 and provides a convenient way to load and validate a driver class.
352 The most common pattern when taking a driver class as a parameter is to
354 check that the name is a class (i.e. check against _CLASS) and then to
355 load the class (if it exists) and then ensure that the class returns
356 true for the isa method on some base driver name.
357 Return the value as a convenience, or "undef" if the value is not a
359 class name, the module does not exist, the module does not load, or the
360 class fails the isa test.
361
363 - Add _CAN to help resolve the UNIVERSAL::can debacle
364 - Would be even nicer if someone would demonstrate how the hell to
366 build a Module::Install dist of the ::Util dual Perl/XS type. :/
367 - Implement an assertion-like version of this module, that dies on
369 error.
370 - Implement a Test:: version of this module, for use in testing
372
374 Bugs should be reported via the CPAN bug tracker at
375 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Params-Util>
377 For other issues, contact the author.
379
381 Adam Kennedy <adamk@cpan.org>
382
384 Params::Validate
385
387 Copyright 2005 - 2009 Adam Kennedy.
388 This program is free software; you can redistribute it and/or modify it
390 under the same terms as Perl itself.
391 The full text of the license can be found in the LICENSE file included
393 with this module.
394perl v5.10.1 2009-05-30 Params::Util(3)