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