blib/lib/Params/Util.pm

filter: Statementstmt 100% 27 / 27 Branchbran 83.3% 5 / 6 Conditioncond n/a MC/DCmcdc n/a Subroutinesub 100% 7 / 7 Podpod n/a totaltotal 97.5% 39 / 40 CC 1 SCAR 0.0
CC
1
Cov
97%
BEGIN
1.0
BEGIN
1.0
BEGIN
1.0
CRAP 1.0
« Util.xs ↑ Summary
1 package Params::Util;
2  
3 =pod
4  
5 =head1 NAME
6  
7 Params::Util - Simple, compact and correct param-checking functions
8  
9 =head1 SYNOPSIS
10  
11 # Import some functions
12 use Params::Util qw{_SCALAR _HASH _INSTANCE};
13
14 # If you are lazy, or need a lot of them...
15 use Params::Util ':ALL';
16
17 sub foo {
18 my $object = _INSTANCE(shift, 'Foo') or return undef;
19 my $image = _SCALAR(shift) or return undef;
20 my $options = _HASH(shift) or return undef;
21 # etc...
22 }
23  
24 =head1 DESCRIPTION
25  
26 C<Params::Util> provides a basic set of importable functions that makes
27 checking parameters a hell of a lot easier
28  
29 While they can be (and are) used in other contexts, the main point
30 behind this module is that the functions B<both> Do What You Mean,
31 and Do The Right Thing, so they are most useful when you are getting
32 params passed into your code from someone and/or somewhere else
33 and you can't really trust the quality.
34  
35 Thus, C<Params::Util> is of most use at the edges of your API, where
36 params and data are coming in from outside your code.
37  
38 The functions provided by C<Params::Util> check in the most strictly
39 correct manner known, are documented as thoroughly as possible so their
40 exact behaviour is clear, and heavily tested so make sure they are not
41 fooled by weird data and Really Bad Things.
42  
43 To use, simply load the module providing the functions you want to use
44 as arguments (as shown in the SYNOPSIS).
45  
46 To aid in maintainability, C<Params::Util> will B<never> export by
47 default.
48  
49 You must explicitly name the functions you want to export, or use the
50 C<:ALL> param to just have it export everything (although this is not
51 recommended if you have any _FOO functions yourself with which future
52 additions to C<Params::Util> may clash)
53  
54 =head1 FUNCTIONS
55  
56 =cut
57  
58 18 ▶use 5.00503;
Subroutine BEGIN: called CC=1 SCAR=0.0
59 18 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
60 18 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
61 18 ▶use parent qw{Exporter XSLoader};
Subroutine BEGIN: called CC=1 SCAR=0.0
62  
63 18 ▶use Params::Util::PP qw();
Subroutine BEGIN: called CC=1 SCAR=0.0
64  
65 18 our $VERSION = '1.099_001';
66  
67 18 ▶local $ENV{PERL_DL_NONLAZY} = 0 if $ENV{PERL_DL_NONLAZY};
Branch: 1 branch
BranchTrueFalseTotal
if $ENV{"PERL_DL_NONLAZY"} 18 0 18
68 18 ▶XSLoader::load("Params::Util", $VERSION) unless $ENV{PERL_PARAMS_UTIL_PP};
Branch: 1 branch
BranchTrueFalseTotal
unless $ENV{"PERL_PARAMS_UTIL_PP"} 9 9 18
69  
70 18 our @EXPORT_OK = qw{
71 _STRING _IDENTIFIER
72 _CLASS _CLASSISA _SUBCLASS _DRIVER _CLASSDOES
73 _NUMBER _POSINT _NONNEGINT
74 _SCALAR _SCALAR0
75 _ARRAY _ARRAY0 _ARRAYLIKE
76 _HASH _HASH0 _HASHLIKE
77 _CODE _CODELIKE
78 _INVOCANT _REGEX _INSTANCE _INSTANCEDOES
79 _SET _SET0
80 _HANDLE
81 };
82 18 our %EXPORT_TAGS = (ALL => \@EXPORT_OK);
83  
84 ## no critic (TestingAndDebugging::ProhibitNoStrict)
85 18 ▶no strict "refs";
Subroutine BEGIN: called CC=1 SCAR=0.0
86 18 ▶Params::Util->can($_) or *$_ = Params::Util::PP->can($_) for (@EXPORT_OK);
Branch: 1 branch
BranchTrueFalseTotal
"Params::Util"->can($_) or *$_ = "Params::Util::PP"->can($_) 360 126 486
87 18 ▶use strict "refs";
Subroutine BEGIN: called CC=1 SCAR=0.0
88  
89 #####################################################################
90 # Param Checking Functions
91  
92 =pod
93  
94 =head2 _STRING $string
95  
96 The C<_STRING> function is intended to be imported into your
97 package, and provides a convenient way to test to see if a value is
98 a normal non-false string of non-zero length.
99  
100 Note that this will NOT do anything magic to deal with the special
101 C<'0'> false negative case, but will return it.
102  
103 # '0' not considered valid data
104 my $name = _STRING(shift) or die "Bad name";
105
106 # '0' is considered valid data
107 my $string = _STRING($_[0]) ? shift : die "Bad string";
108  
109 Please also note that this function expects a normal string. It does
110 not support overloading or other magic techniques to get a string.
111  
112 Returns the string as a convenience if it is a valid string, or
113 C<undef> if not.
114  
115 =head2 _IDENTIFIER $string
116  
117 The C<_IDENTIFIER> function is intended to be imported into your
118 package, and provides a convenient way to test to see if a value is
119 a string that is a valid Perl identifier.
120  
121 Returns the string as a convenience if it is a valid identifier, or
122 C<undef> if not.
123  
124 =head2 _CLASS $string
125  
126 The C<_CLASS> function is intended to be imported into your
127 package, and provides a convenient way to test to see if a value is
128 a string that is a valid Perl class.
129  
130 This function only checks that the format is valid, not that the
131 class is actually loaded. It also assumes "normalized" form, and does
132 not accept class names such as C<::Foo> or C<D'Oh>.
133  
134 Returns the string as a convenience if it is a valid class name, or
135 C<undef> if not.
136  
137 =head2 _CLASSISA $string, $class
138  
139 The C<_CLASSISA> function is intended to be imported into your
140 package, and provides a convenient way to test to see if a value is
141 a string that is a particularly class, or a subclass of it.
142  
143 This function checks that the format is valid and calls the -E<gt>isa
144 method on the class name. It does not check that the class is actually
145 loaded.
146  
147 It also assumes "normalized" form, and does
148 not accept class names such as C<::Foo> or C<D'Oh>.
149  
150 Returns the string as a convenience if it is a valid class name, or
151 C<undef> if not.
152  
153 =head2 _CLASSDOES $string, $role
154  
155 This routine behaves exactly like C<L</_CLASSISA>>, but checks with C<< ->DOES
156 >> rather than C<< ->isa >>. This is probably only a good idea to use on Perl
157 5.10 or later, when L<UNIVERSAL::DOES|UNIVERSAL::DOES/DOES> has been
158 implemented.
159  
160 =head2 _SUBCLASS $string, $class
161  
162 The C<_SUBCLASS> function is intended to be imported into your
163 package, and provides a convenient way to test to see if a value is
164 a string that is a subclass of a specified class.
165  
166 This function checks that the format is valid and calls the -E<gt>isa
167 method on the class name. It does not check that the class is actually
168 loaded.
169  
170 It also assumes "normalized" form, and does
171 not accept class names such as C<::Foo> or C<D'Oh>.
172  
173 Returns the string as a convenience if it is a valid class name, or
174 C<undef> if not.
175  
176 =head2 _NUMBER $scalar
177  
178 The C<_NUMBER> function is intended to be imported into your
179 package, and provides a convenient way to test to see if a value is
180 a number. That is, it is defined and perl thinks it's a number.
181  
182 This function is basically a Params::Util-style wrapper around the
183 L<Scalar::Util> C<looks_like_number> function.
184  
185 Returns the value as a convenience, or C<undef> if the value is not a
186 number.
187  
188 =head2 _POSINT $integer
189  
190 The C<_POSINT> function is intended to be imported into your
191 package, and provides a convenient way to test to see if a value is
192 a positive integer (of any length).
193  
194 Returns the value as a convenience, or C<undef> if the value is not a
195 positive integer.
196  
197 The name itself is derived from the XML schema constraint of the same
198 name.
199  
200 =head2 _NONNEGINT $integer
201  
202 The C<_NONNEGINT> function is intended to be imported into your
203 package, and provides a convenient way to test to see if a value is
204 a non-negative integer (of any length). That is, a positive integer,
205 or zero.
206  
207 Returns the value as a convenience, or C<undef> if the value is not a
208 non-negative integer.
209  
210 As with other tests that may return false values, care should be taken
211 to test via "defined" in boolean validly contexts.
212  
213 unless ( defined _NONNEGINT($value) ) {
214 die "Invalid value";
215 }
216  
217 The name itself is derived from the XML schema constraint of the same
218 name.
219  
220 =head2 _SCALAR \$scalar
221  
222 The C<_SCALAR> function is intended to be imported into your package,
223 and provides a convenient way to test for a raw and unblessed
224 C<SCALAR> reference, with content of non-zero length.
225  
226 For a version that allows zero length C<SCALAR> references, see
227 the C<_SCALAR0> function.
228  
229 Returns the C<SCALAR> reference itself as a convenience, or C<undef>
230 if the value provided is not a C<SCALAR> reference.
231  
232 =head2 _SCALAR0 \$scalar
233  
234 The C<_SCALAR0> function is intended to be imported into your package,
235 and provides a convenient way to test for a raw and unblessed
236 C<SCALAR0> reference, allowing content of zero-length.
237  
238 For a simpler "give me some content" version that requires non-zero
239 length, C<_SCALAR> function.
240  
241 Returns the C<SCALAR> reference itself as a convenience, or C<undef>
242 if the value provided is not a C<SCALAR> reference.
243  
244 =head2 _ARRAY $value
245  
246 The C<_ARRAY> function is intended to be imported into your package,
247 and provides a convenient way to test for a raw and unblessed
248 C<ARRAY> reference containing B<at least> one element of any kind.
249  
250 For a more basic form that allows zero length ARRAY references, see
251 the C<_ARRAY0> function.
252  
253 Returns the C<ARRAY> reference itself as a convenience, or C<undef>
254 if the value provided is not an C<ARRAY> reference.
255  
256 =head2 _ARRAY0 $value
257  
258 The C<_ARRAY0> function is intended to be imported into your package,
259 and provides a convenient way to test for a raw and unblessed
260 C<ARRAY> reference, allowing C<ARRAY> references that contain no
261 elements.
262  
263 For a more basic "An array of something" form that also requires at
264 least one element, see the C<_ARRAY> function.
265  
266 Returns the C<ARRAY> reference itself as a convenience, or C<undef>
267 if the value provided is not an C<ARRAY> reference.
268  
269 =head2 _ARRAYLIKE $value
270  
271 The C<_ARRAYLIKE> function tests whether a given scalar value can respond to
272 array dereferencing. If it can, the value is returned. If it cannot,
273 C<_ARRAYLIKE> returns C<undef>.
274  
275 =head2 _HASH $value
276  
277 The C<_HASH> function is intended to be imported into your package,
278 and provides a convenient way to test for a raw and unblessed
279 C<HASH> reference with at least one entry.
280  
281 For a version of this function that allows the C<HASH> to be empty,
282 see the C<_HASH0> function.
283  
284 Returns the C<HASH> reference itself as a convenience, or C<undef>
285 if the value provided is not an C<HASH> reference.
286  
287 =head2 _HASH0 $value
288  
289 The C<_HASH0> function is intended to be imported into your package,
290 and provides a convenient way to test for a raw and unblessed
291 C<HASH> reference, regardless of the C<HASH> content.
292  
293 For a simpler "A hash of something" version that requires at least one
294 element, see the C<_HASH> function.
295  
296 Returns the C<HASH> reference itself as a convenience, or C<undef>
297 if the value provided is not an C<HASH> reference.
298  
299 =head2 _HASHLIKE $value
300  
301 The C<_HASHLIKE> function tests whether a given scalar value can respond to
302 hash dereferencing. If it can, the value is returned. If it cannot,
303 C<_HASHLIKE> returns C<undef>.
304  
305 =head2 _CODE $value
306  
307 The C<_CODE> function is intended to be imported into your package,
308 and provides a convenient way to test for a raw and unblessed
309 C<CODE> reference.
310  
311 Returns the C<CODE> reference itself as a convenience, or C<undef>
312 if the value provided is not an C<CODE> reference.
313  
314 =head2 _CODELIKE $value
315  
316 The C<_CODELIKE> is the more generic version of C<_CODE>. Unlike C<_CODE>,
317 which checks for an explicit C<CODE> reference, the C<_CODELIKE> function
318 also includes things that act like them, such as blessed objects that
319 overload C<'&{}'>.
320  
321 Please note that in the case of objects overloaded with '&{}', you will
322 almost always end up also testing it in 'bool' context at some stage.
323  
324 For example:
325  
326 sub foo {
327 my $code1 = _CODELIKE(shift) or die "No code param provided";
328 my $code2 = _CODELIKE(shift);
329 if ( $code2 ) {
330 print "Got optional second code param";
331 }
332 }
333  
334 As such, you will most likely always want to make sure your class has
335 at least the following to allow it to evaluate to true in boolean
336 context.
337  
338 # Always evaluate to true in boolean context
339 use overload 'bool' => sub () { 1 };
340  
341 Returns the callable value as a convenience, or C<undef> if the
342 value provided is not callable.
343  
344 Note - This function was formerly known as _CALLABLE but has been renamed
345 for greater symmetry with the other _XXXXLIKE functions.
346  
347 The use of _CALLABLE has been deprecated. It will continue to work, but
348 with a warning, until end-2006, then will be removed.
349  
350 I apologize for any inconvenience caused.
351  
352 =head2 _INVOCANT $value
353  
354 This routine tests whether the given value is a valid method invocant.
355 This can be either an instance of an object, or a class name.
356  
357 If so, the value itself is returned. Otherwise, C<_INVOCANT>
358 returns C<undef>.
359  
360 =head2 _INSTANCE $object, $class
361  
362 The C<_INSTANCE> function is intended to be imported into your package,
363 and provides a convenient way to test for an object of a particular class
364 in a strictly correct manner.
365  
366 Returns the object itself as a convenience, or C<undef> if the value
367 provided is not an object of that type.
368  
369 =head2 _INSTANCEDOES $object, $role
370  
371 This routine behaves exactly like C<L</_INSTANCE>>, but checks with C<< ->DOES
372 >> rather than C<< ->isa >>. This is probably only a good idea to use on Perl
373 5.10 or later, when L<UNIVERSAL::DOES|UNIVERSAL::DOES/DOES> has been
374 implemented.
375  
376 =head2 _REGEX $value
377  
378 The C<_REGEX> function is intended to be imported into your package,
379 and provides a convenient way to test for a regular expression.
380  
381 Returns the value itself as a convenience, or C<undef> if the value
382 provided is not a regular expression.
383  
384 =head2 _SET \@array, $class
385  
386 The C<_SET> function is intended to be imported into your package,
387 and provides a convenient way to test for set of at least one object of
388 a particular class in a strictly correct manner.
389  
390 The set is provided as a reference to an C<ARRAY> of objects of the
391 class provided.
392  
393 For an alternative function that allows zero-length sets, see the
394 C<_SET0> function.
395  
396 Returns the C<ARRAY> reference itself as a convenience, or C<undef> if
397 the value provided is not a set of that class.
398  
399 =head2 _SET0 \@array, $class
400  
401 The C<_SET0> function is intended to be imported into your package,
402 and provides a convenient way to test for a set of objects of a
403 particular class in a strictly correct manner, allowing for zero objects.
404  
405 The set is provided as a reference to an C<ARRAY> of objects of the
406 class provided.
407  
408 For an alternative function that requires at least one object, see the
409 C<_SET> function.
410  
411 Returns the C<ARRAY> reference itself as a convenience, or C<undef> if
412 the value provided is not a set of that class.
413  
414 =head2 _HANDLE
415  
416 The C<_HANDLE> function is intended to be imported into your package,
417 and provides a convenient way to test whether or not a single scalar
418 value is a file handle.
419  
420 Unfortunately, in Perl the definition of a file handle can be a little
421 bit fuzzy, so this function is likely to be somewhat imperfect (at first
422 anyway).
423  
424 That said, it is implement as well or better than the other file handle
425 detectors in existence (and we stole from the best of them).
426  
427 =head2 _DRIVER $string
428  
429 sub foo {
430 my $class = _DRIVER(shift, 'My::Driver::Base') or die "Bad driver";
431 ...
432 }
433  
434 The C<_DRIVER> function is intended to be imported into your
435 package, and provides a convenient way to load and validate
436 a driver class.
437  
438 The most common pattern when taking a driver class as a parameter
439 is to check that the name is a class (i.e. check against _CLASS)
440 and then to load the class (if it exists) and then ensure that
441 the class returns true for the isa method on some base driver name.
442  
443 Return the value as a convenience, or C<undef> if the value is not
444 a class name, the module does not exist, the module does not load,
445 or the class fails the isa test.
446  
447 =head1 TO DO
448  
449 - Add _CAN to help resolve the UNIVERSAL::can debacle
450  
451 - Implement an assertion-like version of this module, that dies on
452 error.
453  
454 - Implement a Test:: version of this module, for use in testing
455  
456 =head1 SUPPORT
457  
458 Bugs should be reported via the CPAN bug tracker at
459  
460 L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Params-Util>
461  
462 =head1 AUTHOR
463  
464 Adam Kennedy E<lt>adamk AT cpan.orgE<gt>
465  
466 Jens Rehsack E<lt>rehsack AT cpan.orgE<gt>
467  
468 =head1 SEE ALSO
469  
470 L<Params::Validate>
471  
472 =head1 COPYRIGHT
473  
474 Copyright 2005 - 2012 Adam Kennedy.
475  
476 Copyright 2020 - 2020 Jens Rehsack.
477  
478 This program is free software; you can redistribute
479 it and/or modify it under the same terms as Perl itself.
480  
481 The full text of the license can be found in the
482 LICENSE file included with this module.
483  
484 =cut
485  
486 18 1;
« Util.xs ↑ Summary