1Params::Util(3) User Contributed Perl Documentation Params::Util(3)
2
3
4
6 Params::Util - Simple, compact and correct param-checking functions
7
9 # Import some functions
10 use Params::Util qw{_SCALAR _HASH _INSTANCE};
11
12 # If you are lazy, or need a lot of them...
13 use Params::Util ':ALL';
14
15 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
26 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
32 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
35 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
40 To use, simply load the module providing the functions you want to use
41 as arguments (as shown in the SYNOPSIS).
42
43 To aid in maintainability, "Params::Util" will never export by default.
44
45 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
56 Note that this will NOT do anything magic to deal with the special '0'
57 false negative case, but will return it.
58
59 # '0' not considered valid data
60 my $name = _STRING(shift) or die "Bad name";
61
62 # '0' is considered valid data
63 my $string = _STRING($_[0]) ? shift : die "Bad string";
64
65 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
68 Returns the string as a conveince if it is a valid string, or "undef"
69 if not.
70
71 _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
76 Returns the string as a convenience if it is a valid identifier, or
77 "undef" if not.
78
79 _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
84 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
88 Returns the string as a convenience if it is a valid class name, or
89 "undef" if not.
90
91 _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
96 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
100 It also assumes "normalised" form, and does not accept class names such
101 as "::Foo" or "D'Oh".
102
103 Returns the string as a convenience if it is a valid class name, or
104 "undef" if not.
105
106 _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
111 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
115 It also assumes "normalised" form, and does not accept class names such
116 as "::Foo" or "D'Oh".
117
118 Returns the string as a convenience if it is a valid class name, or
119 "undef" if not.
120
121 _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
126 This function is basically a Params::Util-style wrapper around the
127 Scalar::Util "looks_like_number" function.
128
129 Returns the value as a convience, or "undef" if the value is not a
130 number.
131
132 _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
137 Returns the value as a convience, or "undef" if the value is not a
138 positive integer.
139
140 The name itself is derived from the XML schema constraint of the same
141 name.
142
143 _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
148 Returns the value as a convience, or "undef" if the value is not a non-
149 negative integer.
150
151 As with other tests that may return false values, care should be taken
152 to test via "defined" in boolean validy contexts.
153
154 unless ( defined _NONNEGINT($value) ) {
155 die "Invalid value";
156 }
157
158 The name itself is derived from the XML schema constraint of the same
159 name.
160
161 _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
166 For a version that allows zero length "SCALAR" references, see the
167 "_SCALAR0" function.
168
169 Returns the "SCALAR" reference itself as a convenience, or "undef" if
170 the value provided is not a "SCALAR" reference.
171
172 _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
177 For a simpler "give me some content" version that requires non-zero
178 length, "_SCALAR" function.
179
180 Returns the "SCALAR" reference itself as a convenience, or "undef" if
181 the value provided is not a "SCALAR" reference.
182
183 _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
188 For a more basic form that allows zero length ARRAY references, see the
189 "_ARRAY0" function.
190
191 Returns the "ARRAY" reference itself as a convenience, or "undef" if
192 the value provided is not an "ARRAY" reference.
193
194 _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
199 For a more basic "An array of something" form that also requires at
200 least one element, see the "_ARRAY" function.
201
202 Returns the "ARRAY" reference itself as a convenience, or "undef" if
203 the value provided is not an "ARRAY" reference.
204
205 _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
210 _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
215 For a version of this function that allows the "HASH" to be empty, see
216 the "_HASH0" function.
217
218 Returns the "HASH" reference itself as a convenience, or "undef" if the
219 value provided is not an "HASH" reference.
220
221 _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
226 For a simpler "A hash of something" version that requires at least one
227 element, see the "_HASH" function.
228
229 Returns the "HASH" reference itself as a convenience, or "undef" if the
230 value provided is not an "HASH" reference.
231
232 _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
237 _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
242 Returns the "CODE" reference itself as a convenience, or "undef" if the
243 value provided is not an "CODE" reference.
244
245 _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
251 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
254 For example:
255
256 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
264 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
268 # Always evaluate to true in boolean context
269 use overload 'bool' => sub () { 1 };
270
271 Returns the callable value as a convenience, or "undef" if the value
272 provided is not callable.
273
274 Note - This function was formerly known as _CALLABLE but has been
275 renamed for greater symmetry with the other _XXXXLIKE functions.
276
277 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
280 I apologise for any inconvenience caused.
281
282 _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
286 If so, the value itself is returned. Otherwise, "_INVOCANT" returns
287 "undef".
288
289 _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
294 Returns the object itself as a convenience, or "undef" if the value
295 provided is not an object of that type.
296
297 _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
301 Returns the value itself as a convenience, or "undef" if the value
302 provided is not a regular expression.
303
304 _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
309 The set is provided as a reference to an "ARRAY" of objects of the
310 class provided.
311
312 For an alternative function that allows zero-length sets, see the
313 "_SET0" function.
314
315 Returns the "ARRAY" reference itself as a convenience, or "undef" if
316 the value provided is not a set of that class.
317
318 _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
323 The set is provided as a reference to an "ARRAY" of objects of the
324 class provided.
325
326 For an alternative function that requires at least one object, see the
327 "_SET" function.
328
329 Returns the "ARRAY" reference itself as a convenience, or "undef" if
330 the value provided is not a set of that class.
331
332 _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
337 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
341 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
344 _DRIVER $string
345 sub foo {
346 my $class = _DRIVER(shift, 'My::Driver::Base') or die "Bad driver";
347 ...
348 }
349
350 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
353 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
358 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
365 - 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
368 - Implement an assertion-like version of this module, that dies on
369 error.
370
371 - Implement a Test:: version of this module, for use in testing
372
374 Bugs should be reported via the CPAN bug tracker at
375
376 http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Params-Util
377 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Params-Util>
378
379 For other issues, contact the author.
380
382 Adam Kennedy <adamk@cpan.org>
383
385 Params::Validate
386
388 Copyright 2005 - 2011 Adam Kennedy.
389
390 This program is free software; you can redistribute it and/or modify it
391 under the same terms as Perl itself.
392
393 The full text of the license can be found in the LICENSE file included
394 with this module.
395
396
397
398perl v5.12.3 2011-04-20 Params::Util(3)