1Params::Util(3)       User Contributed Perl Documentation      Params::Util(3)
2
3
4

NAME

6       Params::Util - Simple, compact and correct param-checking functions
7

SYNOPSIS

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

DESCRIPTION

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

FUNCTIONS

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   _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
111   _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
116       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
120       It also assumes "normalised" form, and does not accept class names such
121       as "::Foo" or "D'Oh".
122
123       Returns the string as a convenience if it is a valid class name, or
124       "undef" if not.
125
126   _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
131       This function is basically a Params::Util-style wrapper around the
132       Scalar::Util "looks_like_number" function.
133
134       Returns the value as a convience, or "undef" if the value is not a
135       number.
136
137   _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
142       Returns the value as a convience, or "undef" if the value is not a
143       positive integer.
144
145       The name itself is derived from the XML schema constraint of the same
146       name.
147
148   _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
153       Returns the value as a convience, or "undef" if the value is not a non-
154       negative integer.
155
156       As with other tests that may return false values, care should be taken
157       to test via "defined" in boolean validy contexts.
158
159         unless ( defined _NONNEGINT($value) ) {
160            die "Invalid value";
161         }
162
163       The name itself is derived from the XML schema constraint of the same
164       name.
165
166   _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
171       For a version that allows zero length "SCALAR" references, see the
172       "_SCALAR0" function.
173
174       Returns the "SCALAR" reference itself as a convenience, or "undef" if
175       the value provided is not a "SCALAR" reference.
176
177   _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
182       For a simpler "give me some content" version that requires non-zero
183       length, "_SCALAR" function.
184
185       Returns the "SCALAR" reference itself as a convenience, or "undef" if
186       the value provided is not a "SCALAR" reference.
187
188   _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
193       For a more basic form that allows zero length ARRAY references, see the
194       "_ARRAY0" function.
195
196       Returns the "ARRAY" reference itself as a convenience, or "undef" if
197       the value provided is not an "ARRAY" reference.
198
199   _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
204       For a more basic "An array of something" form that also requires at
205       least one element, see the "_ARRAY" function.
206
207       Returns the "ARRAY" reference itself as a convenience, or "undef" if
208       the value provided is not an "ARRAY" reference.
209
210   _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
215   _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
220       For a version of this function that allows the "HASH" to be empty, see
221       the "_HASH0" function.
222
223       Returns the "HASH" reference itself as a convenience, or "undef" if the
224       value provided is not an "HASH" reference.
225
226   _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
231       For a simpler "A hash of something" version that requires at least one
232       element, see the "_HASH" function.
233
234       Returns the "HASH" reference itself as a convenience, or "undef" if the
235       value provided is not an "HASH" reference.
236
237   _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
242   _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
247       Returns the "CODE" reference itself as a convenience, or "undef" if the
248       value provided is not an "CODE" reference.
249
250   _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
256       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
259       For example:
260
261         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
269       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
273         # Always evaluate to true in boolean context
274         use overload 'bool' => sub () { 1 };
275
276       Returns the callable value as a convenience, or "undef" if the value
277       provided is not callable.
278
279       Note - This function was formerly known as _CALLABLE but has been
280       renamed for greater symmetry with the other _XXXXLIKE functions.
281
282       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
285       I apologise for any inconvenience caused.
286
287   _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
291       If so, the value itself is returned.  Otherwise, "_INVOCANT" returns
292       "undef".
293
294   _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
299       Returns the object itself as a convenience, or "undef" if the value
300       provided is not an object of that type.
301
302   _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
307   _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
311       Returns the value itself as a convenience, or "undef" if the value
312       provided is not a regular expression.
313
314   _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
319       The set is provided as a reference to an "ARRAY" of objects of the
320       class provided.
321
322       For an alternative function that allows zero-length sets, see the
323       "_SET0" function.
324
325       Returns the "ARRAY" reference itself as a convenience, or "undef" if
326       the value provided is not a set of that class.
327
328   _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
333       The set is provided as a reference to an "ARRAY" of objects of the
334       class provided.
335
336       For an alternative function that requires at least one object, see the
337       "_SET" function.
338
339       Returns the "ARRAY" reference itself as a convenience, or "undef" if
340       the value provided is not a set of that class.
341
342   _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
347       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
351       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
354   _DRIVER $string
355         sub foo {
356           my $class = _DRIVER(shift, 'My::Driver::Base') or die "Bad driver";
357           ...
358         }
359
360       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
363       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
368       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

TO DO

373       - Add _CAN to help resolve the UNIVERSAL::can debacle
374
375       - 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
378       - Implement an assertion-like version of this module, that dies on
379       error.
380
381       - Implement a Test:: version of this module, for use in testing
382

SUPPORT

384       Bugs should be reported via the CPAN bug tracker at
385
386       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Params-Util>
387
388       For other issues, contact the author.
389

AUTHOR

391       Adam Kennedy <adamk@cpan.org>
392

SEE ALSO

394       Params::Validate
395
397       Copyright 2005 - 2012 Adam Kennedy.
398
399       This program is free software; you can redistribute it and/or modify it
400       under the same terms as Perl itself.
401
402       The full text of the license can be found in the LICENSE file included
403       with this module.
404
405
406
407perl v5.16.3                      2012-03-11                   Params::Util(3)
Impressum