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   _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

TO DO

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

SUPPORT

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

AUTHOR

382       Adam Kennedy <adamk@cpan.org>
383

SEE ALSO

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)
Impressum