Profile of Params/Util.pm

Filename	/Users/ether/.perlbrew/libs/36.0@std/lib/perl5/darwin-2level/Params/Util.pm
Statements	Executed 21 statements in 5.06ms

Subroutines
Calls	P	F	Exclusive Time	Inclusive Time	Subroutine
1	1	1	1.96ms	2.06ms	Params::Util::::BEGIN@63Params::Util::BEGIN@63
56	2	1	55µs	55µs	Params::Util::::_STRINGParams::Util::_STRING (xsub)
1	1	1	20µs	20µs	Params::Util::::BEGIN@58Params::Util::BEGIN@58
1	1	1	6µs	9µs	Params::Util::::BEGIN@59Params::Util::BEGIN@59
1	1	1	6µs	24µs	Params::Util::::BEGIN@61Params::Util::BEGIN@61
1	1	1	5µs	11µs	Params::Util::::BEGIN@85Params::Util::BEGIN@85
1	1	1	5µs	7µs	Params::Util::::BEGIN@87Params::Util::BEGIN@87
1	1	1	3µs	30µs	Params::Util::::BEGIN@60Params::Util::BEGIN@60

Call graph for these subroutines as a Graphviz dot language file.

Line	State ments	Time on line	Calls	Time in subs	Code
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	2	38µs	1	20µs	# spent 20µs within Params::Util::BEGIN@58 which was called: # once (20µs+0s) by File::ShareDir::BEGIN@1.26 at line 58 use 5.00503; # spent 20µs making 1 call to Params::Util::BEGIN@58
59	2	18µs	2	12µs	# spent 9µs (6+3) within Params::Util::BEGIN@59 which was called: # once (6µs+3µs) by File::ShareDir::BEGIN@1.26 at line 59 use strict; # spent 9µs making 1 call to Params::Util::BEGIN@59 # spent 3µs making 1 call to strict::import
60	2	16µs	2	57µs	# spent 30µs (3+27) within Params::Util::BEGIN@60 which was called: # once (3µs+27µs) by File::ShareDir::BEGIN@1.26 at line 60 use warnings; # spent 30µs making 1 call to Params::Util::BEGIN@60 # spent 27µs making 1 call to warnings::import
61	2	18µs	2	42µs	# spent 24µs (6+18) within Params::Util::BEGIN@61 which was called: # once (6µs+18µs) by File::ShareDir::BEGIN@1.26 at line 61 use parent qw{Exporter XSLoader}; # spent 24µs making 1 call to Params::Util::BEGIN@61 # spent 18µs making 1 call to parent::import
62
63	2	567µs	1	2.06ms	# spent 2.06ms (1.96+101µs) within Params::Util::BEGIN@63 which was called: # once (1.96ms+101µs) by File::ShareDir::BEGIN@1.26 at line 63 use Params::Util::PP qw(); # spent 2.06ms making 1 call to Params::Util::BEGIN@63
64
65	1	0s			our $VERSION = '1.102';
66
67	1	0s			local $ENV{PERL_DL_NONLAZY} = 0 if $ENV{PERL_DL_NONLAZY};
68	1	3.70ms	1	3.69ms	XSLoader::load("Params::Util", $VERSION) unless $ENV{PERL_PARAMS_UTIL_PP}; # spent 3.69ms making 1 call to XSLoader::load
69
70	1	5µs			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	1	2µs			our %EXPORT_TAGS = (ALL => \@EXPORT_OK);
83
84					## no critic (TestingAndDebugging::ProhibitNoStrict)
85	2	34µs	2	17µs	# spent 11µs (5+6) within Params::Util::BEGIN@85 which was called: # once (5µs+6µs) by File::ShareDir::BEGIN@1.26 at line 85 no strict "refs"; # spent 11µs making 1 call to Params::Util::BEGIN@85 # spent 6µs making 1 call to strict::unimport
86	1	129µs	40	54µs	Params::Util->can($_) or *$_ = Params::Util::PP->can($_) for (@EXPORT_OK); # spent 54µs making 40 calls to UNIVERSAL::can, avg 1µs/call
87	2	523µs	2	9µs	# spent 7µs (5+2) within Params::Util::BEGIN@87 which was called: # once (5µs+2µs) by File::ShareDir::BEGIN@1.26 at line 87 use strict "refs"; # spent 7µs making 1 call to Params::Util::BEGIN@87 # spent 2µs making 1 call to strict::import
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	1	12µs			1;

					# spent 55µs within Params::Util::_STRING which was called 56 times, avg 982ns/call: # 42 times (31µs+0s) by List::MoreUtils::XS::firstres at line 462 of File/ShareDir.pm, avg 738ns/call # 14 times (24µs+0s) by File::ShareDir::_DIST at line 511 of File/ShareDir.pm, avg 2µs/call sub Params::Util::_STRING; # xsub