1Type::Tiny::Manual::ParUasmesr(3C)ontributed Perl DocumeTnytpaet:i:oTniny::Manual::Params(3)
2
3
4

NAME

6       Type::Tiny::Manual::Params - advanced information on Type::Params
7

MANUAL

9       To get started with Type::Params, please read
10       Type::Tiny::Manual::UsingWithMoo which will cover a lot of the basics,
11       even if you're not using Moo.
12
13   "validate" and "validate_named"
14       The generally recommended way of using Type::Params is this:
15
16         sub mysub {
17           state $check = compile( SIGNATURE );
18           my @args = $check->( @_ );
19         }
20
21       But it is possible to do it in one call:
22
23         sub mysub {
24           my @args = validate( \@_, SIGNATURE );
25         }
26
27       There is also a "validate_named" function which acts as a counterpart
28       for "compile_named".
29
30       This will generally be slower and less efficient than using "compile"
31       first because Type::Tiny can do a lot of optimizations in that first
32       stage to make the second stage a lot faster. (And the results of
33       "compile" get stored in the "state" variable so that only has to happen
34       once.)
35
36       There is rarely a reason to use "validate" and "validate_named", but
37       they exist if you want them.
38
39   "multisig"
40       Multisig allows you to allow multiple ways of calling a sub.
41
42        sub repeat_string {
43          state $check = multisig(
44            compile(
45              Int,
46              Str,
47            ),
48            compile_named(
49              { named_to_list => 1 },
50              count  => Int,
51              string => Str,
52            ),
53          );
54
55          my ($count, $string) = $check->(@_);
56          return $string x $count;
57        }
58
59        repeat_string(            "Hello",          42  );    # works
60        repeat_string(  string => "Hello", count => 42  );    # works
61        repeat_string({ string => "Hello", count => 42 });    # works
62        repeat_string( qr/hiya/ );                            # dies
63
64       It combines multiple checks and tries each until one works.
65
66   "wrap_subs" and "wrap_methods"
67       "wrap_subs" turns the "compile" idea inside out.
68
69       Instead of this:
70
71        sub foobar {
72          state $check = compile(Int, Str);
73          my ($foo, $bar) = @_;
74          ...;
75        }
76
77       You do this:
78
79        sub foobar {
80          my ($foo, $bar) = @_;
81          ...;
82        }
83        wrap_subs foobar => [ Int, Str ];
84
85       Or this:
86
87        sub foobar {
88          my ($foo, $bar) = @_;
89          ...;
90        }
91        wrap_subs foobar => compile( Int, Str );
92
93   Mixed Named and Positional Parameters
94       This can be faked using positional parameters and a slurpy dictionary.
95
96        state $check = compile(
97          Int,
98          slurpy Dict[
99            foo => Int,
100            bar => Optional[Int],
101            baz => Optional[Int],
102          ],
103        );
104
105        @_ = (42, foo => 21);                 # ok
106        @_ = (42, foo => 21, bar  => 84);     # ok
107        @_ = (42, foo => 21, bar  => 10.5);   # not ok
108        @_ = (42, foo => 21, quux => 84);     # not ok
109
110   Proper Signatures
111       Don't you wish your subs could look like this?
112
113         sub set_name (Object $self, Str $name) {
114           $self->{name} = $name;
115         }
116
117       Well; here are a few solutions for sub signatures that work with
118       Type::Tiny...
119
120       Kavorka
121
122       Kavorka is a sub signatures implementation written to natively use
123       Type::Utils' "dwim_type" for type constraints, and take advantage of
124       Type::Tiny's features such as inlining, and coercions.
125
126         method set_name (Str $name) {
127           $self->{name} = $name;
128         }
129
130       Kavorka's signatures provide a lot more flexibility, and slightly more
131       speed than Type::Params. (The speed comes from inlining almost all type
132       checks into the body of the sub being declared.)
133
134       Kavorka also includes support for type checking of the returned value.
135
136       Kavorka can also be used as part of Moops, a larger framework for
137       object oriented programming in Perl.
138
139       Function::Parameters
140
141       Function::Parameters offers support for Type::Tiny and MooseX::Types.
142
143         use Types::Standard qw( Str );
144         use Function::Parameters;
145
146         method set_name (Str $name) {
147             $self->{name} = $name;
148         }
149
150       Attribute::Contract
151
152       Both Kavorka and Function::Parameters require a relatively recent
153       version of Perl. Attribute::Contract supports older versions by using a
154       lot less magic.
155
156       You want Attribute::Contract 0.03 or above.
157
158         use Attribute::Contract -types => [qw/Object Str/];
159
160         sub set_name :ContractRequires(Object, Str) {
161             my ($self, $name) = @_;
162             $self->{name} = $name;
163         }
164
165       Attribute::Contract also includes support for type checking of the
166       returned value.
167
168   Type::Params versus X
169       Params::Validate
170
171       Type::Params is not really a drop-in replacement for Params::Validate;
172       the API differs far too much to claim that. Yet it performs a similar
173       task, so it makes sense to compare them.
174
175       ·   Type::Params will tend to be faster if you've got a sub which is
176           called repeatedly, but may be a little slower than Params::Validate
177           for subs that are only called a few times. This is because it does
178           a bunch of work the first time your sub is called to make
179           subsequent calls a lot faster.
180
181       ·   Params::Validate doesn't appear to have a particularly natural way
182           of validating a mix of positional and named parameters.
183
184       ·   Type::Utils allows you to coerce parameters. For example, if you
185           expect a Path::Tiny object, you could coerce it from a string.
186
187       ·   If you are primarily writing object-oriented code, using Moose or
188           similar, and you are using Type::Tiny type constraints for your
189           attributes, then using Type::Params allows you to use the same
190           constraints for method calls.
191
192       ·   Type::Params comes bundled with Types::Standard, which provides a
193           much richer vocabulary of types than the type validation constants
194           that come with Params::Validate. For example, Types::Standard
195           provides constraints like "ArrayRef[Int]" (an arrayref of
196           integers), while the closest from Params::Validate is "ARRAYREF",
197           which you'd need to supplement with additional callbacks if you
198           wanted to check that the arrayref contained integers.
199
200           Whatsmore, Type::Params doesn't just work with Types::Standard, but
201           also any other Type::Tiny type constraints.
202
203       Params::ValidationCompiler
204
205       Params::ValidationCompiler does basically the same thing as
206       Type::Params.
207
208       ·   Params::ValidationCompiler and Type::Params are likely to perform
209           fairly similarly. In most cases, recent versions of Type::Params
210           seem to be slightly faster, but except in very trivial cases,
211           you're unlikely to notice the speed difference. Speed probably
212           shouldn't be a factor when choosing between them.
213
214       ·   Type::Params's syntax is more compact:
215
216              state $check = compile(Object, Optional[Int], slurpy ArrayRef);
217
218           Versus:
219
220              state $check = validation_for(
221                 params => [
222                    { type => Object },
223                    { type => Int,      optional => 1 },
224                    { type => ArrayRef, slurpy => 1 },
225                 ],
226              );
227
228       ·   Params::ValidationCompiler probably has slightly better exceptions.
229

NEXT STEPS

231       Here's your next step:
232
233       ·   Type::Tiny::Manual::NonOO
234
235           Type::Tiny in non-object-oriented code.
236

AUTHOR

238       Toby Inkster <tobyink@cpan.org>.
239

241       This software is copyright (c) 2013-2014, 2017-2020 by Toby Inkster.
242
243       This is free software; you can redistribute it and/or modify it under
244       the same terms as the Perl 5 programming language system itself.
245

DISCLAIMER OF WARRANTIES

247       THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
248       WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
249       MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
250
251
252
253perl v5.30.1                      2020-02-12     Type::Tiny::Manual::Params(3)
Impressum