1Type::Params(3) User Contributed Perl Documentation Type::Params(3)
2
6 Type::Params - sub signature validation using Type::Tiny type
7 constraints and coercions
8
10 use v5.20;
11 use strict;
12 use warnings;
13 use experimental 'signatures';
14 package Horse {
16 use Moo;
17 use Types::Standard qw( Object );
18 use Type::Params -sigs;
19 use namespace::autoclean;
20 ...; # define attributes, etc
22 signature_for add_child => (
24 method => 1,
25 positional => [ Object ],
26 );
27 sub add_child ( $self, $child ) {
29 push @{ $self->children }, $child;
31 return $self;
33 }
34 }
35 package main;
37 my $boldruler = Horse->new;
39 $boldruler->add_child( Horse->new );
41 $boldruler->add_child( 123 ); # dies (123 is not an Object!)
43
45 This module is covered by the Type-Tiny stability policy.
46
48 This documents the details of the Type::Params package.
49 Type::Tiny::Manual is a better starting place if you're new.
50 Type::Params uses Type::Tiny constraints to validate the parameters to
52 a sub. It takes the slightly unorthodox approach of separating
53 validation into two stages:
54 1. Compiling the parameter specification into a coderef; then
56 2. Using the coderef to validate parameters.
58 The first stage is slow (it might take a couple of milliseconds), but
60 you only need to do it the first time the sub is called. The second
61 stage is fast; according to my benchmarks faster even than the XS
62 version of Params::Validate.
63
65 The modern API can be exported using:
66 use Type::Params -sigs;
68 Or:
70 use Type::Params -v2;
72 Or by requesting functions by name:
74 use Type::Params qw( signature signature_for );
76 signature( %spec )
78 The "signature" function takes a specification for your function's
79 signature and returns a coderef. You then call the coderef in list
80 context, passing @_ to it. The coderef will check, coerce, and apply
81 other procedures to the values, and return the tidied values, or die
82 with an error.
83 The usual way of using it is:
85 sub your_function {
87 state $signature = signature( ... );
88 my ( $arg1, $arg2, $arg3 ) = $signature->( @_ );
89 ...;
91 }
92 Perl allows a slightly archaic way of calling coderefs without using
94 parentheses, which may be slightly faster at the cost of being more
95 obscure:
96 sub your_function {
98 state $signature = signature( ... );
99 my ( $arg1, $arg2, $arg3 ) = &$signature;
100 ...;
102 }
103 If you need to support Perl 5.8, which didn't have the "state" keyword:
105 my $__your_function_sig;
107 sub your_function {
108 $__your_function_sig ||= signature( ... );
109 my ( $arg1, $arg2, $arg3 ) = $__your_function_sig->( @_ );
110 ...;
112 }
113 One important thing to note is how the signature is only compiled into
115 a coderef the first time your function gets called, and thereafter will
116 be reused.
117 Signature Specification Options
119 The signature specification is a hash which must contain either a
121 "positional", "named", or "multiple" key indicating whether your
122 function takes positional parameters, named parameters, or supports
123 multiple calling conventions, but may also include other options.
124 "positional" ArrayRef
126 This is conceptually a list of type constraints, one for each
128 positional parameter. For example, a signature for a function which
129 accepts two integers:
130 signature( positional => [ Int, Int ] )
132 However, each type constraint is optionally followed by a hashref of
134 options which affect that parameter. For example:
135 signature( positional => [
137 Int, { default => 40 },
138 Int, { default => 2 },
139 ] )
140 Type constraints can instead be given as strings, which will be looked
142 up using "dwim_type" from Type::Utils.
143 signature( positional => [
145 'Int', { default => 40 },
146 'Int', { default => 2 },
147 ] )
148 See the section below for more information on parameter options.
150 Optional parameters must follow required parameters, and can be
152 specified using either the Optional parameterizable type constraint,
153 the "optional" parameter option, or by providing a default.
154 signature( positional => [
156 Optional[Int],
157 Int, { optional => !!1 },
158 Int, { default => 42 },
159 ] )
160 A single slurpy parameter may be provided at the end, using the Slurpy
162 parameterizable type constraint, or the "slurpy" parameter option:
163 signature( positional => [
165 Int,
166 Slurpy[ ArrayRef[Int] ],
167 ] )
168 signature( positional => [
170 Int,
171 ArrayRef[Int], { slurpy => !!1 },
172 ] )
173 The "positional" option can also be abbreviated to "pos".
175 So "signature( pos => [...] )" can be used instead of the longer
177 "signature( positional => [...] )".
178 If a signature uses positional parameters, the values are returned by
180 the coderef as a list:
181 sub add_numbers {
183 state $sig = signature( positional => [ Num, Num ] );
184 my ( $num1, $num2 ) = $sig->( @_ );
185 return $num1 + $num2;
187 }
188 say add_numbers( 2, 3 ); # says 5
190 "named" ArrayRef
192 This is conceptually a list of pairs of names and type constraints, one
194 name+type pair for each positional parameter. For example, a signature
195 for a function which accepts two integers:
196 signature( named => [ foo => Int, bar => Int ] )
198 However, each type constraint is optionally followed by a hashref of
200 options which affect that parameter. For example:
201 signature( named => [
203 foo => Int, { default => 40 },
204 bar => Int, { default => 2 },
205 ] )
206 Type constraints can instead be given as strings, which will be looked
208 up using "dwim_type" from Type::Utils.
209 signature( named => [
211 foo => 'Int', { default => 40 },
212 bar => 'Int', { default => 2 },
213 ] )
214 Optional and slurpy parameters are allowed, but unlike positional
216 parameters, they do not need to be at the end.
217 See the section below for more information on parameter options.
219 If a signature uses named parameters, the values are returned by the
221 coderef as an object:
222 sub add_numbers {
224 state $sig = signature( named => [ num1 => Num, num2 => Num ] );
225 my ( $arg ) = $sig->( @_ );
226 return $arg->num1 + $arg->num2;
228 }
229 say add_numbers( num1 => 2, num2 => 3 ); # says 5
231 say add_numbers( { num1 => 2, num2 => 3 } ); # also says 5
232 "named_to_list" ArrayRef|Bool
234 The "named_to_list" option is ignored for signatures using positional
236 parameters, but for signatures using named parameters, allows them to
237 be returned in a list instead of as an object:
238 sub add_numbers {
240 state $sig = signature(
241 named => [ num1 => Num, num2 => Num ],
242 named_to_list => !!1,
243 );
244 my ( $num1, $num2 ) = $sig->( @_ );
245 return $num1 + $num2;
247 }
248 say add_numbers( num1 => 2, num2 => 3 ); # says 5
250 say add_numbers( { num1 => 2, num2 => 3 } ); # also says 5
251 You can think of "add_numbers" above as a function which takes named
253 parameters from the outside, but receives positional parameters on the
254 inside.
255 You can use an arrayref to specify the order the paramaters will be
257 returned in. (By default they are returned in the order they were
258 defined in.)
259 sub add_numbers {
261 state $sig = signature(
262 named => [ num1 => Num, num2 => Num ],
263 named_to_list => [ qw( num2 num1 ) ],
264 );
265 my ( $num2, $num1 ) = $sig->( @_ );
266 return $num1 + $num2;
268 }
269 "head" Int|ArrayRef
271 "head" provides an additional list of non-optional, positional
273 parameters at the start of @_. This is often used for method calls. For
274 example, if you wish to define a signature for:
275 $object->my_method( foo => 123, bar => 456 );
277 You could write it as this:
279 sub my_method {
281 state $signature = signature(
282 head => [ Object ],
283 named => [ foo => Optional[Int], bar => Optional[Int] ],
284 );
285 my ( $self, $arg ) = $signature->( @_ );
286 ...;
288 }
289 If "head" is set as a number instead of an arrayref, it is the number
291 of additional arguments at the start:
292 sub my_method {
294 state $signature = signature(
295 head => 1,
296 named => [ foo => Optional[Int], bar => Optional[Int] ],
297 );
298 my ( $self, $arg ) = $signature->( @_ );
299 ...;
301 }
302 In this case, no type checking is performed on those additional
304 arguments; it is just checked that they exist.
305 "tail" Int|ArrayRef
307 A "tail" is like a "head" except that it is for arguments at the end of
309 @_.
310 sub my_method {
312 state $signature = signature(
313 head => [ Object ],
314 named => [ foo => Optional[Int], bar => Optional[Int] ],
315 tail => [ CodeRef ],
316 );
317 my ( $self, $arg, $callback ) = $signature->( @_ );
318 ...;
320 }
321 $object->my_method( foo => 123, bar => 456, sub { ... } );
323 "method" Bool|TypeTiny
325 While "head" can be used for method signatures, a more declarative way
327 is to set "method => 1".
328 If you wish to be specific that this is an object method, intended to
330 be called on blessed objects only, then you may use "method => Object",
331 using the Object type from Types::Standard. If you wish to specify that
332 it's a class method, then use "method => Str", using the Str type from
333 Types::Standard. ("method => ClassName" is perhaps clearer, but it's a
334 slower check.)
335 sub my_method {
337 state $signature = signature(
338 method => 1,
339 named => [ foo => Optional[Int], bar => Optional[Int] ],
340 );
341 my ( $self, $arg ) = $signature->( @_ );
342 ...;
344 }
345 If "method" is true (or a type constraint) then any parameter defaults
347 which are coderefs will be called as methods.
348 "description" Str
350 This is the description of the coderef that will show up in stack
352 traces. It defaults to "parameter validation for X" where X is the
353 caller sub name. Usually the default will be fine.
354 "package" Str
356 The package of the sub whose paramaters we're supposed to be checking.
358 As well as showing up in stack traces, it's used by "dwim_type" if you
359 provide any type constraints as strings.
360 The default is probably fine, but if you're wrapping "signature" so
362 that you can check signatures on behalf of another package, you may
363 need to provide it.
364 "subname" Str
366 The name of the sub whose paramaters we're supposed to be checking.
368 The default is probably fine, but if you're wrapping "signature" so
370 that you can check signatures on behalf of another package, you may
371 need to provide it.
372 "caller_level" Int
374 If you're wrapping "signature" so that you can check signatures on
376 behalf of another package, then setting "caller_level" to 1 (or more,
377 depending on the level of wrapping!) may be an alternative to manually
378 setting the "package" and "subname".
379 "on_die" Maybe[CodeRef]
381 Usually when your coderef hits an error, it will throw an exception,
383 which is a blessed Error::TypeTiny object.
384 If you provide an "on_die" coderef, then instead the Error::TypeTiny
386 object will be passed to it. If the "on_die" coderef returns something,
387 then whatever it returns will be returned as your signature's
388 parameters.
389 sub add_numbers {
391 state $sig = signature(
392 positional => [ Num, Num ],
393 on_die => sub {
394 my $error = shift;
395 print "Existential crisis: $error\n";
396 exit( 1 );
397 },
398 );
399 my ( $num1, $num2 ) = $sig->( @_ );
400 return $num1 + $num2;
402 }
403 say add_numbers(); # has an existential crisis
405 This is probably not very useful.
407 "goto_next" Bool|CodeLike
409 This can be used for chaining coderefs. If you understand "on_die",
411 it's more like an "on_live".
412 sub add_numbers {
414 state $sig = signature(
415 positional => [ Num, Num ],
416 goto_next => sub {
417 my ( $num1, $num2 ) = @_;
418 return $num1 + $num2;
420 },
421 );
422 my $sum = $sig->( @_ );
424 return $sum;
425 }
426 say add_numbers( 2, 3 ); # says 5
428 If set to a true boolean instead of a coderef, has a slightly different
430 behaviour:
431 sub add_numbers {
433 state $sig = signature(
434 positional => [ Num, Num ],
435 goto_next => !!1,
436 );
437 my $sum = $sig->(
439 sub { return $_[0] + $_[1] },
440 @_,
441 );
442 return $sum;
443 }
444 say add_numbers( 2, 3 ); # says 5
446 This looks strange. Why would this be useful? Well, it works nicely
448 with Moose's "around" keyword.
449 sub add_numbers {
451 return $_[1] + $_[2];
452 }
453 around add_numbers => signature(
455 method => !!1,
456 positional => [ Num, Num ],
457 goto_next => !!1,
458 package => __PACKAGE__,
459 subname => 'add_numbers',
460 );
461 say __PACKAGE__->add_numbers( 2, 3 ); # says 5
463 Note the way "around" works in Moose is that it expects a wrapper
465 coderef as its final argument. That wrapper coderef then expects to be
466 given a reference to the original function as its first parameter.
467 This can allow, for example, a role to provide a signature wrapping a
469 method defined in a class.
470 This is kind of complex, and you're unlikely to use it, but it's been
472 proven useful for tools that integrate Type::Params with Moose-like
473 method modifiers.
474 "strictness" Bool|Str
476 If you set "strictness" to a false value (0, undef, or the empty
478 string), then certain signature checks will simply never be done. The
479 initial check that there's the correct number of parameters, plus type
480 checks on parameters which don't coerce can be skipped.
481 If you set it to a true boolean (i.e. 1) or do not set it at all, then
483 these checks will always be done.
484 Alternatively, it may be set to the quoted fully-qualified name of a
486 Perl global variable or a constant, and that will be compiled into the
487 coderef as a condition to enable strict checks.
488 state $signature = signature(
490 strictness => '$::CHECK_TYPES',
491 positional => [ Int, ArrayRef ],
492 );
493 # Type checks are skipped
495 {
496 local $::CHECK_TYPES = 0;
497 my ( $number, $list ) = $signature->( {}, {} );
498 }
499 # Type checks are performed
501 {
502 local $::CHECK_TYPES = 1;
503 my ( $number, $list ) = $signature->( {}, {} );
504 }
505 A recommended use of this is with Devel::StrictMode.
507 use Devel::StrictMode qw( STRICT );
509 state $signature = signature(
511 strictness => STRICT,
512 positional => [ Int, ArrayRef ],
513 );
514 "multiple" ArrayRef
516 This option allows your signature to support multiple calling
518 conventions. Each entry in the array is an alternative signature, as a
519 hashref:
520 state $signature = signature(
522 multiple => [
523 {
524 positional => [ ArrayRef, Int ],
525 },
526 {
527 named => [ array => ArrayRef, index => Int ],
528 named_to_list => 1,
529 },
530 ],
531 );
532 That signature will allow your function to be called as:
534 your_function( $arr, $ix )
536 your_function( array => $arr, index => $ix )
537 your_function( { array => $arr, index => $ix } )
538 Sometimes the alternatives will return the parameters in a different
540 order:
541 state $signature = signature(
543 multiple => [
544 { positional => [ ArrayRef, Int ] },
545 { positional => [ Int, ArrayRef ] },
546 ],
547 );
548 my ( $xxx, $yyy ) = $signature->( @_ );
549 So how does your sub know whether $xxx or $yyy is the arrayref? One
551 option is to use the "${^_TYPE_PARAMS_MULTISIG}" global variable which
552 will be set to the index of the signature which was used:
553 my @results = $signature->( @_ );
555 my ( $arr, $ix ) = ${^_TYPE_PARAMS_MULTISIG} == 1
556 ? reverse( @results )
557 : @results;
558 A neater solution is to use a "goto_next" coderef to re-order
560 alternative signature results into your preferred order:
561 state $signature = signature(
563 multiple => [
564 { positional => [ ArrayRef, Int ] },
565 { positional => [ Int, ArrayRef ], goto_next => sub { reverse @_ } },
566 ],
567 );
568 my ( $arr, $ix ) = $signature->( @_ );
569 While conceptally "multiple" is an arrayref of hashrefs, it is also
571 possible to use arrayrefs in the arrayref.
572 multiple => [
574 [ ArrayRef, Int ],
575 [ Int, ArrayRef ],
576 ]
577 When an arrayref is used like that, it is a shortcut for a positional
579 signature.
580 Coderefs may additionally be used:
582 state $signature = signature(
584 multiple => [
585 [ ArrayRef, Int ],
586 { positional => [ Int, ArrayRef ], goto_next => sub { reverse @_ } },
587 sub { ... },
588 sub { ... },
589 ],
590 );
591 The coderefs should be subs which return a list of parameters if they
593 succeed and throw an exception if they fail.
594 The following signatures are equivalent:
596 state $sig_1 = signature(
598 multiple => [
599 { method => 1, positional => [ ArrayRef, Int ] },
600 { method => 1, positional => [ Int, ArrayRef ] },
601 ],
602 );
603 state $sig_2 = signature(
605 method => 1,
606 multiple => [
607 { positional => [ ArrayRef, Int ] },
608 { positional => [ Int, ArrayRef ] },
609 ],
610 );
611 The "multiple" option can also be abbreviated to "multi".
613 So "signature( multi => [...] )" can be used instead of the longer
615 "signature( multiple => [...] )". Three whole keystrokes saved!
616 (Note: in older releases of Type::Params, "${^_TYPE_PARAMS_MULTISIG}"
618 was called "${^TYPE_PARAMS_MULTISIG}". The latter name is deprecated,
619 and support for it will be removed in a future release of
620 Type::Params.)
621 "message" Str
623 Only used by "multiple" signatures. The error message to throw when no
625 signatures match.
626 "want_source" Bool
628 Instead of returning a coderef, return Perl source code string. Handy
630 for debugging.
631 "want_details" Bool
633 Instead of returning a coderef, return a hashref of stuff including the
635 coderef. This is mostly for people extending Type::Params and I won't
636 go into too many details about what else this hashref contains.
637 "bless" Bool|ClassName, "class" ClassName|ArrayRef, and "constructor"
639 Str
640 Named parameters are usually returned as a blessed object:
642 sub add_numbers {
644 state $sig = signature( named => [ num1 => Num, num2 => Num ] );
645 my ( $arg ) = $sig->( @_ );
646 return $arg->num1 + $arg->num2;
648 }
649 The class they are blessed into is one built on-the-fly by
651 Type::Params. However, these three signature options allow you more
652 control over that process.
653 Firstly, if you set "bless => false" and do not set "class" or
655 "constructor", then $arg will just be an unblessed hashref.
656 sub add_numbers {
658 state $sig = signature(
659 named => [ num1 => Num, num2 => Num ],
660 bless => !!0,
661 );
662 my ( $arg ) = $sig->( @_ );
663 return $arg->{num1} + $arg->{num2};
665 }
666 This is a good speed boost, but having proper methods for each named
668 parameter is a helpful way to catch misspelled names.
669 If you wish to manually create a class instead of relying on
671 Type::Params generating one on-the-fly, you can do this:
672 package Params::For::AddNumbers {
674 sub num1 { return $_[0]{num1} }
675 sub num2 { return $_[0]{num2} }
676 sub sum {
677 my $self = shift;
678 return $self->num1 + $self->num2;
679 }
680 }
681 sub add_numbers {
683 state $sig = signature(
684 named => [ num1 => Num, num2 => Num ],
685 bless => 'Params::For::AddNumbers',
686 );
687 my ( $arg ) = $sig->( @_ );
688 return $arg->sum;
690 }
691 Note that "Params::For::AddNumbers" here doesn't include a "new" method
693 because Type::Params will directly do "bless( $arg, $opts{bless} )".
694 If you want Type::Params to use a proper constructor, you should use
696 the "class" option instead:
697 package Params::For::AddNumbers {
699 use Moo;
700 has [ 'num1', 'num2' ] => ( is => 'ro' );
701 sub sum {
702 my $self = shift;
703 return $self->num1 + $self->num2;
704 }
705 }
706 sub add_numbers {
708 state $sig = signature(
709 named => [ num1 => Num, num2 => Num ],
710 class => 'Params::For::AddNumbers',
711 );
712 my ( $arg ) = $sig->( @_ );
713 return $arg->sum;
715 }
716 If you wish to use a constructor named something other than "new", then
718 use:
719 state $sig = signature(
721 named => [ num1 => Num, num2 => Num ],
722 class => 'Params::For::AddNumbers',
723 constructor => 'new_from_hashref',
724 );
725 Or as a shortcut:
727 state $sig = signature(
729 named => [ num1 => Num, num2 => Num ],
730 class => [ 'Params::For::AddNumbers', 'new_from_hashref' ],
731 );
732 It is doubtful you want to use any of these options, except "bless =>
734 false".
735 Parameter Options
737 In the parameter lists for the "positional" and "named" signature
739 options, each parameter may be followed by a hashref of options
740 specific to that parameter:
741 signature(
743 positional => [
744 Int, \%options_for_first_parameter,
745 Int, \%options_for_other_parameter,
746 ],
747 %more_options_for_signature,
748 );
749 signature(
751 named => [
752 foo => Int, \%options_for_foo,
753 bar => Int, \%options_for_bar,
754 ],
755 %more_options_for_signature,
756 );
757 The following options are supported for parameters.
759 "optional" Bool
761 An option called optional!
763 This makes a parameter optional:
765 sub add_nums {
767 state $sig = signature(
768 positional => [
769 Int,
770 Int,
771 Bool, { optional => !!1 },
772 ],
773 );
774 my ( $num1, $num2, $debug ) = $sig->( @_ );
776 my $sum = $num1 + $num2;
778 warn "$sum = $num1 + $num2" if $debug;
779 return $sum;
781 }
782 add_nums( 2, 3, 1 ); # prints warning
784 add_nums( 2, 3, 0 ); # no warning
785 add_nums( 2, 3 ); # no warning
786 Types::Standard also provides a Optional parameterizable type which may
788 be a neater way to do this:
789 state $sig = signature(
791 positional => [ Int, Int, Optional[Bool] ],
792 );
793 In signatures with positional parameters, any optional parameters must
795 be defined after non-optional parameters. The "tail" option provides a
796 workaround for required parameters at the end of @_.
797 In signatures with named parameters, the order of optional and non-
799 optional parameters is unimportant.
800 "slurpy" Bool
802 A signature may contain a single slurpy parameter, which mops up any
804 other arguments the caller provides your function.
805 In signatures with positional parameters, slurpy params must always
807 have some kind of ArrayRef or HashRef type constraint, must always
808 appear at the end of the list of positional parameters, and they work
809 like this:
810 sub add_nums {
812 state $sig = signature(
813 positional => [
814 Num,
815 ArrayRef[Num], { slurpy => !!1 },
816 ],
817 );
818 my ( $first_num, $other_nums ) = $sig->( @_ );
819 my $sum = $first_num;
821 $sum += $_ for @$other_nums;
822 return $sum;
824 }
825 say add_nums( 1 ); # says 1
827 say add_nums( 1, 2 ); # says 3
828 say add_nums( 1, 2, 3 ); # says 6
829 say add_nums( 1, 2, 3, 4 ); # says 10
830 In signatures with named parameters, slurpy params must always have
832 some kind of HashRef type constraint, and they work like this:
833 use builtin qw( true false );
835 sub process_data {
837 state $sig = signature(
838 method => true,
839 named => [
840 input => FileHandle,
841 output => FileHandle,
842 flags => HashRef[Bool], { slurpy => true },
843 ],
844 );
845 my ( $self, $arg ) = @_;
846 warn "Beginning data processing" if $arg->flags->{debug};
847 ...;
849 }
850 $widget->process_data(
852 input => \*STDIN,
853 output => \*STDOUT,
854 debug => true,
855 );
856 The Slurpy type constraint from Types::Standard may be used as a
858 shortcut to specify slurpy parameters:
859 signature(
861 positional => [ Num, Slurpy[ ArrayRef[Num] ] ],
862 )
863 The type Slurpy[Any] is handled specially and treated as a slurpy
865 ArrayRef in signatures with positional parameters, and a slurpy HashRef
866 in signatures with named parameters, but has some additional
867 optimizations for speed.
868 "default" CodeRef|ScalarRef|Ref|Str|Undef
870 A default may be provided for a parameter.
872 state $check = signature(
874 positional => [
875 Int,
876 Int, { default => "666" },
877 Int, { default => "999" },
878 ],
879 );
880 Supported defaults are any strings (including numerical ones), "undef",
882 and empty hashrefs and arrayrefs. Non-empty hashrefs and arrayrefs are
883 not allowed as defaults.
884 Alternatively, you may provide a coderef to generate a default value:
886 state $check = signature(
888 positional => [
889 Int,
890 Int, { default => sub { 6 * 111 } },
891 Int, { default => sub { 9 * 111 } },
892 ]
893 );
894 That coderef may generate any value, including non-empty arrayrefs and
896 non-empty hashrefs. For undef, simple strings, numbers, and empty
897 structures, avoiding using a coderef will make your parameter
898 processing faster.
899 Instead of a coderef, you can use a reference to a string of Perl
901 source code:
902 state $check = signature(
904 positional => [
905 Int,
906 Int, { default => \ '6 * 111' },
907 Int, { default => \ '9 * 111' },
908 ],
909 );
910 Defaults will be validated against the type constraint, and potentially
912 coerced.
913 Any parameter with a default will automatically be optional.
915 Note that having any defaults in a signature (even if they never end up
917 getting used) can slow it down, as Type::Params will need to build a
918 new array instead of just returning @_.
919 "coerce" Bool
921 Speaking of which, the "coerce" option allows you to indicate that a
923 value should be coerced into the correct type:
924 state $sig = signature(
926 positional => [
927 Int,
928 Int,
929 Bool, { coerce => true },
930 ],
931 );
932 Setting "coerce" to false will disable coercion.
934 If "coerce" is not specified, so is neither true nor false, then
936 coercion will be enabled if the type constraint has a coercion, and
937 disabled otherwise.
938 Note that having any coercions in a signature (even if they never end
940 up getting used) can slow it down, as Type::Params will need to build a
941 new array instead of just returning @_.
942 "clone" Bool
944 If this is set to true, it will deep clone incoming values via "dclone"
946 from Storable (a core module since Perl 5.7.3).
947 In the below example, $arr is a reference to a clone of @numbers, so
949 pushing additional numbers to it leaves @numbers unaffected.
950 sub foo {
952 state $check = signature(
953 positional => [
954 ArrayRef, { clone => 1 }
955 ],
956 );
957 my ( $arr ) = &$check;
958 push @$arr, 4, 5, 6;
960 }
961 my @numbers = ( 1, 2, 3 );
963 foo( \@numbers );
964 print "@numbers\n"; ## 1 2 3
966 Note that cloning will significantly slow down your signature.
968 "name" Str
970 This overrides the name of a named parameter. I don't know why you
972 would want to do that.
973 The following signature has two parameters: "foo" and "bar". The name
975 "fool" is completely ignored.
976 signature(
978 named => [
979 fool => Int, { name => 'foo' },
980 bar => Int,
981 ],
982 )
983 You can, however, also name positional parameters, which don't usually
985 have names.
986 signature(
988 positional => [
989 Int, { name => 'foo' },
990 Int, { name => 'bar' },
991 ],
992 )
993 The names of positional parameters are not really used for anything at
995 the moment, but may be incorporated into error messages or similar in
996 the future.
997 "getter" Str
999 For signatures with named parameters, specifies the method name used to
1001 retrieve this parameter's value from the $arg object.
1002 sub process_data {
1004 state $sig = signature(
1005 method => true,
1006 named => [
1007 input => FileHandle, { getter => 'in' },
1008 output => FileHandle, { getter => 'out' },
1009 flags => HashRef[Bool], { slurpy => true },
1010 ],
1011 );
1012 my ( $self, $arg ) = @_;
1013 warn "Beginning data processing" if $arg->flags->{debug};
1014 my ( $in, $out ) = ( $arg->in, $arg->out );
1016 ...;
1017 }
1018 $widget->process_data(
1020 input => \*STDIN,
1021 output => \*STDOUT,
1022 debug => true,
1023 );
1024 Ignored by signatures with positional parameters.
1026 "predicate" Str
1028 The $arg object provided by signatures with named parameters will also
1030 include "has" methods for any optional arguments. For example:
1031 state $sig = signature(
1033 method => true,
1034 named => [
1035 input => Optional[ FileHandle ],
1036 output => Optional[ FileHandle ],
1037 flags => Slurpy[ HashRef[Bool] ],
1038 ],
1039 );
1040 my ( $self, $arg ) = $sig->( @_ );
1041 if ( $self->has_input and $self->has_output ) {
1043 ...;
1044 }
1045 Setting a "predicate" option allows you to choose a different name for
1047 this method.
1048 It is also possible to set a "predicate" for non-optional parameters,
1050 which don't normally get a "has" method.
1051 Ignored by signatures with positional parameters.
1053 "alias" Str|ArrayRef[Str]
1055 A list of alternative names for the parameter, or a single alternative
1057 name.
1058 sub add_numbers {
1060 state $sig = signature(
1061 named => [
1062 first_number => Int, { alias => [ 'x' ] },
1063 second_number => Int, { alias => 'y' },
1064 ],
1065 );
1066 my ( $arg ) = $sig->( @_ );
1067 return $arg->first_number + $arg->second_number;
1069 }
1070 say add_numbers( first_number => 40, second_number => 2 ); # 42
1072 say add_numbers( x => 40, y => 2 ); # 42
1073 say add_numbers( first_number => 40, y => 2 ); # 42
1074 say add_numbers( first_number => 40, x => 1, y => 2 ); # dies!
1075 Ignored by signatures with positional parameters.
1077 "strictness" Bool|Str
1079 Overrides the signature option "strictness" on a per-parameter basis.
1081 "signature_for $function_name => ( %spec )"
1083 Like "signature", but instead of returning a coderef, wraps an existing
1084 function, so you don't need to deal with the mechanics of generating
1085 the signature at run-time, calling it, and extracting the returned
1086 values.
1087 The following three examples are roughly equivalent:
1089 sub add_nums {
1091 state $signature = signature(
1092 positional => [ Num, Num ],
1093 );
1094 my ( $x, $y ) = $signature->( @_ );
1095 return $x + $y;
1097 }
1098 Or:
1100 signature_for add_nums => (
1102 positional => [ Num, Num ],
1103 );
1104 sub add_nums {
1106 my ( $x, $y ) = @_;
1107 return $x + $y;
1109 }
1110 Or since Perl 5.20:
1112 signature_for add_nums => (
1114 positional => [ Num, Num ],
1115 );
1116 sub add_nums ( $x, $y ) {
1118 return $x + $y;
1119 }
1120 The "signature_for" keyword turns "signature" inside-out.
1122 The same signature specification options are supported, with the
1124 exception of "want_source", "want_details", and "goto_next" which will
1125 not work. (If using the "multiple" option, then "goto_next" is still
1126 supported in the nested signatures.)
1127 If you are providing a signature for a sub in another package, then
1129 "signature_for "Some::Package::some_sub" => ( ... )" will work, as will
1130 "signature_for some_sub => ( package => "Some::Package", ... )". If
1131 "method" is true, then "signature_for" will respect inheritance when
1132 determining which sub to wrap. "signature_for" will not be able to find
1133 lexical subs, so use "signature" within the sub instead.
1134 The "goto_next" option is what "signature_for" uses to "connect" the
1136 signature to the body of the sub, so do not use it unless you
1137 understand the consequences and want to override the normal behaviour.
1138 If the sub being wrapped cannot be found, then "signature_for" will
1140 usually throw an error. If you want it to "work" in this situation, use
1141 the "fallback" option. "fallback => \&alternative_coderef_to_wrap" will
1142 instead wrap a different coderef if the original cannot be found.
1143 "fallback => 1" is a shortcut for "fallback => sub {}". An example
1144 where this might be useful is if you're adding signatures to methods
1145 which are inherited from a parent class, but you are not 100% confident
1146 will exist (perhaps dependent on the version of the parent class).
1147 signature_for add_nums => (
1149 positional => [ Num, Num ],
1150 fallback => sub { $_[0] + $_[1] },
1151 );
1152 "signature_for( \@functions, %opts )" is a useful shortcut if you have
1154 multiple functions with the same signature.
1155 signature_for [ 'add_nums', 'subtract_nums' ] => (
1157 positional => [ Num, Num ],
1158 );
1159
1161 The following functions were the API prior to Type::Params v2. They are
1162 still supported, but their use is now discouraged.
1163 If you don't provide an import list at all, you will import "compile"
1165 and "compile_named":
1166 use Type::Params;
1168 This does the same:
1170 use Type::Params -v1;
1172 The following exports "compile", "compile_named", and
1174 "compile_named_oo":
1175 use Type::Params -compile;
1177 The following exports "wrap_subs" and "wrap_methods":
1179 use Type::Params -wrap;
1181 compile( @pos_params )
1183 Equivalent to "signature( positional => \@pos_params )".
1184 "compile( \%spec, @pos_params )" is equivalent to "signature( %spec,
1186 positional => \@pos_params )".
1187 compile_named( @named_params )
1189 Equivalent to "signature( bless => 0, named => \@named_params )".
1190 "compile_named( \%spec, @named_params )" is equivalent to "signature(
1192 bless => 0, %spec, named => \@named_params )".
1193 compile_named_oo( @named_params )
1195 Equivalent to "signature( bless => 1, named => \@named_params )".
1196 "compile_named_oo( \%spec, @named_params )" is equivalent to
1198 "signature( bless => 1, %spec, named => \@named_params )".
1199 "validate( \@args, @pos_params )"
1201 Equivalent to "signature( positional => \@pos_params )->( @args )".
1202 The "validate" function has never been recommended, and is not exported
1204 unless requested by name.
1205 "validate_named( \@args, @named_params )"
1207 Equivalent to "signature( bless => 0, named => \@named_params )->(
1208 @args )".
1209 The "validate_named" function has never been recommended, and is not
1211 exported unless requested by name.
1212 "wrap_subs( func1 => \@params1, func2 => \@params2, ... )"
1214 Equivalent to:
1215 signature_for func1 => ( positional => \@params1 );
1217 signature_for func2 => ( positional => \@params2 );
1218 One slight difference is that instead of arrayrefs, you can provide the
1220 output of one of the "compile" functions:
1221 wrap_subs( func1 => compile_named( @params1 ) );
1223 "wrap_subs" is not exported unless requested by name.
1225 "wrap_methods( func1 => \@params1, func2 => \@params2, ... )"
1227 Equivalent to:
1228 signature_for func1 => ( method => 1, positional => \@params1 );
1230 signature_for func2 => ( method => 1, positional => \@params2 );
1231 One slight difference is that instead of arrayrefs, you can provide the
1233 output of one of the "compile" functions:
1234 wrap_methods( func1 => compile_named( @params1 ) );
1236 "wrap_methods" is not exported unless requested by name.
1238 multisig( @alternatives )
1240 Equivalent to:
1241 signature( multiple => \@alternatives )
1243 "multisig( \%spec, @alternatives )" is equivalent to "signature( %spec,
1245 multiple => \@alternatives )".
1246
1248 Although Type::Params is not a real type library, it exports two type
1249 constraints. Their use is no longer recommended.
1250 Invocant
1252 Type::Params exports a type Invocant on request. This gives you a type
1253 constraint which accepts classnames and blessed objects.
1254 use Type::Params qw( compile Invocant );
1256 sub my_method {
1258 state $check = signature(
1259 method => Invocant,
1260 positional => [ ArrayRef, Int ],
1261 );
1262 my ($self_or_class, $arr, $ix) = $check->(@_);
1263 return $arr->[ $ix ];
1265 }
1266 "Invocant" is not exported unless requested by name.
1268 Recommendation: use Defined from Types::Standard instead.
1270 ArgsObject
1272 Type::Params exports a parameterizable type constraint ArgsObject. It
1273 accepts the kinds of objects returned by signature checks for named
1274 parameters.
1275 package Foo {
1277 use Moo;
1278 use Type::Params 'ArgsObject';
1279 has args => (
1281 is => 'ro',
1282 isa => ArgsObject['Bar::bar'],
1283 );
1284 }
1285 package Bar {
1287 use Types::Standard -types;
1288 use Type::Params 'signature';
1289 sub bar {
1291 state $check = signature(
1292 named => [
1293 xxx => Int,
1294 yyy => ArrayRef,
1295 ],
1296 );
1297 my ( $got ) = $check->( @_ );
1298 return 'Foo'->new( args => $got );
1300 }
1301 }
1302 Bar::bar( xxx => 42, yyy => [] );
1304 The parameter "Bar::bar" refers to the caller when the check is
1306 compiled, rather than when the parameters are checked.
1307 "ArgsObject" is not exported unless requested by name.
1309 Recommendation: use Object from Types::Standard instead.
1311
1313 "PERL_TYPE_PARAMS_XS"
1314 Affects the building of accessors for $arg objects. If set to true,
1315 will use Class::XSAccessor. If set to false, will use pure Perl. If
1316 this environment variable does not exist, will use
1317 Class::XSAccessor.
1318 If Class::XSAccessor is not installed or is too old, pure Perl will
1320 always be used as a fallback.
1321
1323 Please report any bugs to
1324 <https://github.com/tobyink/p5-type-tiny/issues>.
1325
1327 The Type::Tiny homepage <https://typetiny.toby.ink/>.
1328 Type::Tiny, Type::Coercion, Types::Standard.
1330
1332 Toby Inkster <tobyink@cpan.org>.
1333
1335 This software is copyright (c) 2013-2014, 2017-2023 by Toby Inkster.
1336 This is free software; you can redistribute it and/or modify it under
1338 the same terms as the Perl 5 programming language system itself.
1339
1341 THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
1342 WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
1343 MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
1344perl v5.36.0 2023-04-24 Type::Params(3)