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       From Type::Params 1.009_002, "head" and "tail" options are accepted,
111       which provide another option for mixed named and positional arguments:
112
113        state $check = compile_named(
114          { head => [ Int ] },
115          foo => Int,
116          bar => Optional[Int],
117          baz => Optional[Int],
118          ],
119        );
120
121       The "head" is shifted off @_ before @_ is considered as a hash.  The
122       "tail" is popped off @_ before @_ is considered as a hash.
123
124   Proper Signatures
125       Don't you wish your subs could look like this?
126
127         sub set_name (Object $self, Str $name) {
128           $self->{name} = $name;
129         }
130
131       Well; here are a few solutions for sub signatures that work with
132       Type::Tiny...
133
134       Zydeco
135
136       Zydeco is a Perl OO syntax toolkit with Type::Tiny support baked in
137       throughout.
138
139         package MyApp {
140           use Zydeco;
141
142           class Person {
143             has name ( type => Str );
144
145             method rename (Str $new_name) {
146               printf("%s will now be called %s\n", $self->name, $new_name);
147               $self->name($new_name);
148             }
149
150             coerce from Str via {
151               $class->new(name => $_)
152             }
153           }
154
155           class Company {
156             has owner ( type => 'Person' );
157           }
158         }
159
160         my $acme = MyApp->new_company(owner => "Robert");
161         $acme->owner->rename("Bob");
162
163       Kavorka
164
165       Kavorka is a sub signatures implementation written to natively use
166       Type::Utils' "dwim_type" for type constraints, and take advantage of
167       Type::Tiny's features such as inlining, and coercions.
168
169         method set_name (Str $name) {
170           $self->{name} = $name;
171         }
172
173       Kavorka's signatures provide a lot more flexibility, and slightly more
174       speed than Type::Params. (The speed comes from inlining almost all type
175       checks into the body of the sub being declared.)
176
177       Kavorka also includes support for type checking of the returned value.
178
179       Kavorka can also be used as part of Moops, a larger framework for
180       object oriented programming in Perl.
181
182       Function::Parameters
183
184       Function::Parameters offers support for Type::Tiny and MooseX::Types.
185
186         use Types::Standard qw( Str );
187         use Function::Parameters;
188
189         method set_name (Str $name) {
190             $self->{name} = $name;
191         }
192
193       Attribute::Contract
194
195       Both Kavorka and Function::Parameters require a relatively recent
196       version of Perl. Attribute::Contract supports older versions by using a
197       lot less magic.
198
199       You want Attribute::Contract 0.03 or above.
200
201         use Attribute::Contract -types => [qw/Object Str/];
202
203         sub set_name :ContractRequires(Object, Str) {
204             my ($self, $name) = @_;
205             $self->{name} = $name;
206         }
207
208       Attribute::Contract also includes support for type checking of the
209       returned value.
210
211   Type::Params versus X
212       Params::Validate
213
214       Type::Params is not really a drop-in replacement for Params::Validate;
215       the API differs far too much to claim that. Yet it performs a similar
216       task, so it makes sense to compare them.
217
218       •   Type::Params will tend to be faster if you've got a sub which is
219           called repeatedly, but may be a little slower than Params::Validate
220           for subs that are only called a few times. This is because it does
221           a bunch of work the first time your sub is called to make
222           subsequent calls a lot faster.
223
224       •   Params::Validate doesn't appear to have a particularly natural way
225           of validating a mix of positional and named parameters.
226
227       •   Type::Utils allows you to coerce parameters. For example, if you
228           expect a Path::Tiny object, you could coerce it from a string.
229
230       •   If you are primarily writing object-oriented code, using Moose or
231           similar, and you are using Type::Tiny type constraints for your
232           attributes, then using Type::Params allows you to use the same
233           constraints for method calls.
234
235       •   Type::Params comes bundled with Types::Standard, which provides a
236           much richer vocabulary of types than the type validation constants
237           that come with Params::Validate. For example, Types::Standard
238           provides constraints like "ArrayRef[Int]" (an arrayref of
239           integers), while the closest from Params::Validate is "ARRAYREF",
240           which you'd need to supplement with additional callbacks if you
241           wanted to check that the arrayref contained integers.
242
243           Whatsmore, Type::Params doesn't just work with Types::Standard, but
244           also any other Type::Tiny type constraints.
245
246       Params::ValidationCompiler
247
248       Params::ValidationCompiler does basically the same thing as
249       Type::Params.
250
251       •   Params::ValidationCompiler and Type::Params are likely to perform
252           fairly similarly. In most cases, recent versions of Type::Params
253           seem to be slightly faster, but except in very trivial cases,
254           you're unlikely to notice the speed difference. Speed probably
255           shouldn't be a factor when choosing between them.
256
257       •   Type::Params's syntax is more compact:
258
259              state $check = compile(Object, Optional[Int], slurpy ArrayRef);
260
261           Versus:
262
263              state $check = validation_for(
264                 params => [
265                    { type => Object },
266                    { type => Int,      optional => 1 },
267                    { type => ArrayRef, slurpy => 1 },
268                 ],
269              );
270
271       •   Params::ValidationCompiler probably has slightly better exceptions.
272

NEXT STEPS

274       Here's your next step:
275
276       •   Type::Tiny::Manual::NonOO
277
278           Type::Tiny in non-object-oriented code.
279

AUTHOR

281       Toby Inkster <tobyink@cpan.org>.
282

284       This software is copyright (c) 2013-2014, 2017-2021 by Toby Inkster.
285
286       This is free software; you can redistribute it and/or modify it under
287       the same terms as the Perl 5 programming language system itself.
288

DISCLAIMER OF WARRANTIES

290       THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
291       WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
292       MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
293
294
295
296perl v5.32.1                      2021-04-27     Type::Tiny::Manual::Params(3)
Impressum