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 20 ▶use 5.00503;
Subroutine BEGIN: called CC=1 SCAR=0.0
59 20 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
60 20 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
61 20 ▶use parent qw{Exporter XSLoader};
Subroutine BEGIN: called CC=1 SCAR=0.0
62  
63 20 ▶use Params::Util::PP qw();
Subroutine BEGIN: called CC=1 SCAR=0.0
64  
65 20 our $VERSION = '1.105_001';
66  
67 20 ▶local $ENV{PERL_DL_NONLAZY} = 0 if $ENV{PERL_DL_NONLAZY};
Branch: 1 branch
BranchTrueFalseTotal
if $ENV{"PERL_DL_NONLAZY"} 20 0 20
68 20 ▶XSLoader::load("Params::Util", $VERSION) unless $ENV{PERL_PARAMS_UTIL_PP};
Branch: 1 branch
BranchTrueFalseTotal
unless $ENV{"PERL_PARAMS_UTIL_PP"} 10 10 20
69  
70 20 our @EXPORT_OK = qw{
71 _STRING _IDENTIFIER
72 _CLASS _CLASSISA _CLASSCAN _SUBCLASS _DRIVER _CLASSDOES
73 _NUMBER _POSINT _NONNEGINT
74 _SCALAR _SCALAR0
75 _ARRAY _ARRAY0 _ARRAYLIKE
76 _HASH _HASH0 _HASHLIKE
77 _CODE _CODELIKE
78 _INVOCANT _INVOCANTCAN
79 _REGEX _INSTANCE _INSTANCEDOES _INSTANCECAN
80 _SET _SET0
81 _HANDLE
82 };
83 20 our %EXPORT_TAGS = (ALL => \@EXPORT_OK);
84  
85 ## no critic (TestingAndDebugging::ProhibitNoStrict)
86 20 ▶no strict "refs";
Subroutine BEGIN: called CC=1 SCAR=0.0
87 20 ▶Params::Util->can($_) or *$_ = Params::Util::PP->can($_) for (@EXPORT_OK);
Branch: 1 branch
BranchTrueFalseTotal
"Params::Util"->can($_) or *$_ = "Params::Util::PP"->can($_) 260 340 600
88 20 ▶use strict "refs";
Subroutine BEGIN: called CC=1 SCAR=0.0
89  
90 #####################################################################
91 # Param Checking Functions
92  
93 =pod
94  
95 =head2 _STRING $string
96  
97 The C<_STRING> function is intended to be imported into your
98 package, and provides a convenient way to test to see if a value is
99 a normal non-false string of non-zero length.
100  
101 Note that this will NOT do anything magic to deal with the special
102 C<'0'> false negative case, but will return it.
103  
104 # '0' not considered valid data
105 my $name = _STRING(shift) or die "Bad name";
106
107 # '0' is considered valid data
108 my $string = _STRING($_[0]) ? shift : die "Bad string";
109  
110 Please also note that this function expects a normal string. It does
111 not support overloading or other magic techniques to get a string.
112  
113 Returns the string as a convenience if it is a valid string, or
114 C<undef> if not.
115  
116 =head2 _IDENTIFIER $string
117  
118 The C<_IDENTIFIER> function is intended to be imported into your
119 package, and provides a convenient way to test to see if a value is
120 a string that is a valid Perl identifier.
121  
122 Returns the string as a convenience if it is a valid identifier, or
123 C<undef> if not.
124  
125 =head2 _CLASS $string
126  
127 The C<_CLASS> function is intended to be imported into your
128 package, and provides a convenient way to test to see if a value is
129 a string that is a valid Perl class.
130  
131 This function only checks that the format is valid, not that the
132 class is actually loaded. It also assumes "normalized" form, and does
133 not accept class names such as C<::Foo> or C<D'Oh>.
134  
135 Returns the string as a convenience if it is a valid class name, or
136 C<undef> if not.
137  
138 =head2 _CLASSISA $string, $class
139  
140 The C<_CLASSISA> function is intended to be imported into your
141 package, and provides a convenient way to test to see if a value is
142 a string that is a particularly class, or a subclass of it.
143  
144 This function checks that the format is valid and calls the -E<gt>isa
145 method on the class name. It does not check that the class is actually
146 loaded.
147  
148 It also assumes "normalized" form, and does
149 not accept class names such as C<::Foo> or C<D'Oh>.
150  
151 Returns the string as a convenience if it is a valid class name, or
152 C<undef> if not.
153  
154 =head2 _CLASSDOES $string, $role
155  
156 This routine behaves exactly like C<L</_CLASSISA>>, but checks with C<< ->DOES
157 >> rather than C<< ->isa >>. This is probably only a good idea to use on Perl
158 5.10 or later, when L<UNIVERSAL::DOES|UNIVERSAL::DOES/DOES> has been
159 implemented.
160  
161 =head2 _CLASSCAN $string, $method
162  
163 The C<_CLASSCAN> function tests whether a value is a valid class name that
164 provides a particular method via C<< ->can >>.
165  
166 This avoids calling C<UNIVERSAL::can> as a function, which is considered
167 problematic because it bypasses any overridden C<can> method.
168  
169 Returns the string as a convenience if it is a valid class name that provides
170 the method, or C<undef> if not.
171  
172 =head2 _SUBCLASS $string, $class
173  
174 The C<_SUBCLASS> function is intended to be imported into your
175 package, and provides a convenient way to test to see if a value is
176 a string that is a subclass of a specified class.
177  
178 This function checks that the format is valid and calls the -E<gt>isa
179 method on the class name. It does not check that the class is actually
180 loaded.
181  
182 It also assumes "normalized" form, and does
183 not accept class names such as C<::Foo> or C<D'Oh>.
184  
185 Returns the string as a convenience if it is a valid class name, or
186 C<undef> if not.
187  
188 =head2 _NUMBER $scalar
189  
190 The C<_NUMBER> 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 number. That is, it is defined and perl thinks it's a number.
193  
194 This function is basically a Params::Util-style wrapper around the
195 L<Scalar::Util> C<looks_like_number> function.
196  
197 Returns the value as a convenience, or C<undef> if the value is not a
198 number.
199  
200 =head2 _POSINT $integer
201  
202 The C<_POSINT> 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 positive integer (of any length).
205  
206 Returns the value as a convenience, or C<undef> if the value is not a
207 positive integer.
208  
209 The name itself is derived from the XML schema constraint of the same
210 name.
211  
212 =head2 _NONNEGINT $integer
213  
214 The C<_NONNEGINT> function is intended to be imported into your
215 package, and provides a convenient way to test to see if a value is
216 a non-negative integer (of any length). That is, a positive integer,
217 or zero.
218  
219 Returns the value as a convenience, or C<undef> if the value is not a
220 non-negative integer.
221  
222 As with other tests that may return false values, care should be taken
223 to test via "defined" in boolean validly contexts.
224  
225 unless ( defined _NONNEGINT($value) ) {
226 die "Invalid value";
227 }
228  
229 The name itself is derived from the XML schema constraint of the same
230 name.
231  
232 =head2 _SCALAR \$scalar
233  
234 The C<_SCALAR> function is intended to be imported into your package,
235 and provides a convenient way to test for a raw and unblessed
236 C<SCALAR> reference, with content of non-zero length.
237  
238 For a version that allows zero length C<SCALAR> references, see
239 the C<_SCALAR0> 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 _SCALAR0 \$scalar
245  
246 The C<_SCALAR0> function is intended to be imported into your package,
247 and provides a convenient way to test for a raw and unblessed
248 C<SCALAR0> reference, allowing content of zero-length.
249  
250 For a simpler "give me some content" version that requires non-zero
251 length, C<_SCALAR> function.
252  
253 Returns the C<SCALAR> reference itself as a convenience, or C<undef>
254 if the value provided is not a C<SCALAR> reference.
255  
256 =head2 _ARRAY $value
257  
258 The C<_ARRAY> 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 containing B<at least> one element of any kind.
261  
262 For a more basic form that allows zero length ARRAY references, see
263 the C<_ARRAY0> function.
264  
265 Returns the C<ARRAY> reference itself as a convenience, or C<undef>
266 if the value provided is not an C<ARRAY> reference.
267  
268 =head2 _ARRAY0 $value
269  
270 The C<_ARRAY0> function is intended to be imported into your package,
271 and provides a convenient way to test for a raw and unblessed
272 C<ARRAY> reference, allowing C<ARRAY> references that contain no
273 elements.
274  
275 For a more basic "An array of something" form that also requires at
276 least one element, see the C<_ARRAY> function.
277  
278 Returns the C<ARRAY> reference itself as a convenience, or C<undef>
279 if the value provided is not an C<ARRAY> reference.
280  
281 =head2 _ARRAYLIKE $value
282  
283 The C<_ARRAYLIKE> function tests whether a given scalar value can respond to
284 array dereferencing. If it can, the value is returned. If it cannot,
285 C<_ARRAYLIKE> returns C<undef>.
286  
287 =head2 _HASH $value
288  
289 The C<_HASH> 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 with at least one entry.
292  
293 For a version of this function that allows the C<HASH> to be empty,
294 see the C<_HASH0> 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 _HASH0 $value
300  
301 The C<_HASH0> function is intended to be imported into your package,
302 and provides a convenient way to test for a raw and unblessed
303 C<HASH> reference, regardless of the C<HASH> content.
304  
305 For a simpler "A hash of something" version that requires at least one
306 element, see the C<_HASH> function.
307  
308 Returns the C<HASH> reference itself as a convenience, or C<undef>
309 if the value provided is not an C<HASH> reference.
310  
311 =head2 _HASHLIKE $value
312  
313 The C<_HASHLIKE> function tests whether a given scalar value can respond to
314 hash dereferencing. If it can, the value is returned. If it cannot,
315 C<_HASHLIKE> returns C<undef>.
316  
317 =head2 _CODE $value
318  
319 The C<_CODE> function is intended to be imported into your package,
320 and provides a convenient way to test for a raw and unblessed
321 C<CODE> reference.
322  
323 Returns the C<CODE> reference itself as a convenience, or C<undef>
324 if the value provided is not an C<CODE> reference.
325  
326 =head2 _CODELIKE $value
327  
328 The C<_CODELIKE> is the more generic version of C<_CODE>. Unlike C<_CODE>,
329 which checks for an explicit C<CODE> reference, the C<_CODELIKE> function
330 also includes things that act like them, such as blessed objects that
331 overload C<'&{}'>.
332  
333 Please note that in the case of objects overloaded with '&{}', you will
334 almost always end up also testing it in 'bool' context at some stage.
335  
336 For example:
337  
338 sub foo {
339 my $code1 = _CODELIKE(shift) or die "No code param provided";
340 my $code2 = _CODELIKE(shift);
341 if ( $code2 ) {
342 print "Got optional second code param";
343 }
344 }
345  
346 As such, you will most likely always want to make sure your class has
347 at least the following to allow it to evaluate to true in boolean
348 context.
349  
350 # Always evaluate to true in boolean context
351 use overload 'bool' => sub () { 1 };
352  
353 Returns the callable value as a convenience, or C<undef> if the
354 value provided is not callable.
355  
356 Note - This function was formerly known as _CALLABLE but has been renamed
357 for greater symmetry with the other _XXXXLIKE functions.
358  
359 The use of _CALLABLE has been deprecated. It will continue to work, but
360 with a warning, until end-2006, then will be removed.
361  
362 I apologize for any inconvenience caused.
363  
364 =head2 _INVOCANT $value
365  
366 This routine tests whether the given value is a valid method invocant.
367 This can be either an instance of an object, or a class name.
368  
369 If so, the value itself is returned. Otherwise, C<_INVOCANT>
370 returns C<undef>.
371  
372 =head2 _INSTANCE $object, $class
373  
374 The C<_INSTANCE> function is intended to be imported into your package,
375 and provides a convenient way to test for an object of a particular class
376 in a strictly correct manner.
377  
378 Returns the object itself as a convenience, or C<undef> if the value
379 provided is not an object of that type.
380  
381 =head2 _INSTANCEDOES $object, $role
382  
383 This routine behaves exactly like C<L</_INSTANCE>>, but checks with C<< ->DOES
384 >> rather than C<< ->isa >>. This is probably only a good idea to use on Perl
385 5.10 or later, when L<UNIVERSAL::DOES|UNIVERSAL::DOES/DOES> has been
386 implemented.
387  
388 =head2 _INSTANCECAN $object, $method
389  
390 This routine behaves exactly like C<L</_INSTANCE>>, but checks with C<< ->can
391 >> rather than C<< ->isa >>. Returns the object as a convenience if it is
392 blessed and provides the specified method, or C<undef> if not.
393  
394 =head2 _INVOCANTCAN $value, $method
395  
396 Tests whether the given value is a valid method invocant (class name or
397 blessed object) that provides a particular method via C<< ->can >>.
398  
399 Returns the value itself as a convenience, or C<undef> if the value is not
400 a valid invocant or does not provide the method.
401  
402 =head2 _REGEX $value
403  
404 The C<_REGEX> function is intended to be imported into your package,
405 and provides a convenient way to test for a regular expression.
406  
407 Returns the value itself as a convenience, or C<undef> if the value
408 provided is not a regular expression.
409  
410 =head2 _SET \@array, $class
411  
412 The C<_SET> function is intended to be imported into your package,
413 and provides a convenient way to test for set of at least one object of
414 a particular class in a strictly correct manner.
415  
416 The set is provided as a reference to an C<ARRAY> of objects of the
417 class provided.
418  
419 For an alternative function that allows zero-length sets, see the
420 C<_SET0> function.
421  
422 Returns the C<ARRAY> reference itself as a convenience, or C<undef> if
423 the value provided is not a set of that class.
424  
425 =head2 _SET0 \@array, $class
426  
427 The C<_SET0> function is intended to be imported into your package,
428 and provides a convenient way to test for a set of objects of a
429 particular class in a strictly correct manner, allowing for zero objects.
430  
431 The set is provided as a reference to an C<ARRAY> of objects of the
432 class provided.
433  
434 For an alternative function that requires at least one object, see the
435 C<_SET> function.
436  
437 Returns the C<ARRAY> reference itself as a convenience, or C<undef> if
438 the value provided is not a set of that class.
439  
440 =head2 _HANDLE
441  
442 The C<_HANDLE> function is intended to be imported into your package,
443 and provides a convenient way to test whether or not a single scalar
444 value is a file handle.
445  
446 Unfortunately, in Perl the definition of a file handle can be a little
447 bit fuzzy, so this function is likely to be somewhat imperfect (at first
448 anyway).
449  
450 That said, it is implement as well or better than the other file handle
451 detectors in existence (and we stole from the best of them).
452  
453 =head2 _DRIVER $string
454  
455 sub foo {
456 my $class = _DRIVER(shift, 'My::Driver::Base') or die "Bad driver";
457 ...
458 }
459  
460 The C<_DRIVER> function is intended to be imported into your
461 package, and provides a convenient way to load and validate
462 a driver class.
463  
464 The most common pattern when taking a driver class as a parameter
465 is to check that the name is a class (i.e. check against _CLASS)
466 and then to load the class (if it exists) and then ensure that
467 the class returns true for the isa method on some base driver name.
468  
469 Return the value as a convenience, or C<undef> if the value is not
470 a class name, the module does not exist, the module does not load,
471 or the class fails the isa test.
472  
473 =head1 TO DO
474  
475 - Implement an assertion-like version of this module, that dies on
476 error. See L<Params::Util::ADR-003> for design considerations.
477  
478 - Implement a Test:: version of this module, for use in testing.
479 See L<Params::Util::ADR-004> for the rationale to ship it as a
480 separate distribution.
481  
482 =head1 SUPPORT
483  
484 Bugs and feature requests should be reported via GitHub Issues at
485  
486 L<https://github.com/perl5-utils/Params-Util/issues>
487  
488 The source repository is at
489  
490 L<https://github.com/perl5-utils/Params-Util>
491  
492 For historical bug reports, see the CPAN RT queue at
493  
494 L<https://rt.cpan.org/Dist/Display.html?Name=Params-Util>
495  
496 =head1 AUTHOR
497  
498 Adam Kennedy E<lt>adamk AT cpan.orgE<gt>
499  
500 Jens Rehsack E<lt>rehsack AT cpan.orgE<gt>
501  
502 =head1 SEE ALSO
503  
504 L<Params::Validate>
505  
506 =head1 COPYRIGHT
507  
508 Copyright 2005 - 2012 Adam Kennedy.
509  
510 Copyright 2020 - 2026 Jens Rehsack.
511  
512 This program is free software; you can redistribute
513 it and/or modify it under the same terms as Perl itself.
514  
515 The full text of the license can be found in the
516 LICENSE file included with this module.
517  
518 =cut
519  
520 20 1;
« Util.xs ↑ Summary