1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
|
=pod
=encoding utf-8
=head1 NAME
Type::Tiny::Manual::Params - advanced information on Type::Params
=head1 MANUAL
To get started with Type::Params, please read
L<Type::Tiny::Manual::UsingWithMoo> which will cover a lot of the basics,
even if you're not using Moo.
=head2 C<multiple>
The C<multiple> option allows you to specify multiple ways of calling
a sub.
sub repeat_string {
state $check = signature(
multiple => [
{ positional => [ Str, Int ] },
{ named => [ string => Str, count => Int ], named_to_list => 1 },
],
);
my ( $string, $count ) = $check->( @_ );
return $string x $count;
}
repeat_string( "Hello", 42 ); # works
repeat_string( string => "Hello", count => 42 ); # works
repeat_string({ string => "Hello", count => 42 }); # works
repeat_string( qr/hiya/ ); # dies
It combines multiple checks and tries each until one works.
=head2 C<signature_for>
C<signature_for> turns C<signature> inside out.
Instead of this:
sub foobar {
state $check = signature( positional => [ Int, Str ] );
my ( $foo, $bar ) = $check->( @_ );
...;
}
You do this:
signature_for foobar => (
positional => [ Int, Str ],
);
sub foobar {
my ( $foo, $bar ) = @_;
...;
}
Or in Perl 5.20+, you can even do this:
signature_for foobar => (
positional => [ Int, Str ],
);
sub foobar ( $foo, $bar ) {
...;
}
=head2 Functions versus Methods
For subs which are intended to be called as functions:
signature( method => 0, ... );
signature( ... ); # this is the default anyway
For subs which are intended to be called as methods on a blessed object:
signature( method => Object, ... );
And for subs which are intended to be called as methods on a class:
signature( method => ClassName, ... );
signature( method => Str, ... ); # less readable, but faster check!
The following is also allowed, which indicates that the sub is intended
to be called as a method, but you don't want to do type checks on the
invocant:
signature( method => 1, ... );
=head2 Mixed Named and Positional Parameters
The C<head> and C<tail> options allow required positional parameters at the
start or end of a named parameter list:
state $check = signature(
head => [ Int ],
named => [
foo => Int,
bar => Optional[Int],
baz => Optional[Int],
],
);
$check->( 42, foo => 21 ); # ok
$check->( 42, foo => 21, bar => 84 ); # ok
$check->( 42, foo => 21, bar => 10.5 ); # not ok
$check->( 42, foo => 21, quux => 84 ); # not ok
=head2 Proper Signatures
Don't you wish your subs could look like this?
sub set_name ( Object $self, Str $name ) {
$self->{name} = $name;
}
Well; here are a few solutions for sub signatures that work with
L<Type::Tiny>...
=head3 Zydeco
L<Zydeco> is a Perl OO syntax toolkit with Type::Tiny support baked in
throughout.
package MyApp {
use Zydeco;
class Person {
has name ( type => Str );
method rename ( Str $new_name ) {
printf( "%s will now be called %s\n", $self->name, $new_name );
$self->name( $new_name );
}
coerce from Str via {
$class->new( name => $_ )
}
}
class Company {
has owner ( type => 'Person' );
}
}
my $acme = MyApp->new_company( owner => "Robert" );
$acme->owner->rename( "Bob" );
=head3 Kavorka
L<Kavorka> is a sub signatures implementation written to natively use
L<Type::Utils>' C<dwim_type> for type constraints, and take advantage
of Type::Tiny's features such as inlining, and coercions.
method set_name ( Str $name ) {
$self->{name} = $name;
}
Kavorka's signatures provide a lot more flexibility, and slightly more
speed than Type::Params. (The speed comes from inlining almost all type
checks into the body of the sub being declared.)
Kavorka also includes support for type checking of the returned value.
Kavorka can also be used as part of L<Moops>, a larger framework for
object oriented programming in Perl.
=head3 Function::Parameters
Function::Parameters offers support for Type::Tiny and MooseX::Types.
use Types::Standard qw( Str );
use Function::Parameters;
method set_name ( Str $name ) {
$self->{name} = $name;
}
=head3 Attribute::Contract
Both Kavorka and Function::Parameters require a relatively recent
version of Perl. L<Attribute::Contract> supports older versions by
using a lot less magic.
You want Attribute::Contract 0.03 or above.
use Attribute::Contract -types => [qw/Object Str/];
sub set_name :ContractRequires(Object, Str) {
my ($self, $name) = @_;
$self->{name} = $name;
}
Attribute::Contract also includes support for type checking of the
returned value.
=head2 Type::Params versus X
=head3 Params::Validate
L<Type::Params> is not really a drop-in replacement for L<Params::Validate>;
the API differs far too much to claim that. Yet it performs a similar task,
so it makes sense to compare them.
=over
=item *
Type::Params will tend to be faster if you've got a sub which is called
repeatedly, but may be a little slower than Params::Validate for subs that
are only called a few times. This is because it does a bunch of work the
first time your sub is called to make subsequent calls a lot faster.
=item *
Params::Validate doesn't appear to have a particularly natural way of
validating a mix of positional and named parameters.
=item *
Type::Utils allows you to coerce parameters. For example, if you expect
a L<Path::Tiny> object, you could coerce it from a string.
=item *
If you are primarily writing object-oriented code, using Moose or similar,
and you are using Type::Tiny type constraints for your attributes, then
using Type::Params allows you to use the same constraints for method calls.
=item *
Type::Params comes bundled with Types::Standard, which provides a much
richer vocabulary of types than the type validation constants that come
with Params::Validate. For example, Types::Standard provides constraints
like C<< ArrayRef[Int] >> (an arrayref of integers), while the closest from
Params::Validate is C<< ARRAYREF >>, which you'd need to supplement with
additional callbacks if you wanted to check that the arrayref contained
integers.
Whatsmore, Type::Params doesn't just work with Types::Standard, but also
any other Type::Tiny type constraints.
=back
=head3 Params::ValidationCompiler
L<Params::ValidationCompiler> does basically the same thing as
L<Type::Params>.
=over
=item *
Params::ValidationCompiler and Type::Params are likely to perform fairly
similarly. In most cases, recent versions of Type::Params seem to be
I<slightly> faster, but except in very trivial cases, you're unlikely to
notice the speed difference. Speed probably shouldn't be a factor when
choosing between them.
=item *
Type::Params's syntax is more compact:
state $check = signature(
pos => [
Object,
Optional[Int],
Slurpy[ArrayRef],
],
);
Versus:
state $check = validation_for(
params => [
{ type => Object },
{ type => Int, optional => 1 },
{ type => ArrayRef, slurpy => 1 },
],
);
=item *
L<Params::ValidationCompiler> probably has slightly better exceptions.
=back
=head1 NEXT STEPS
Here's your next step:
=over
=item * L<Type::Tiny::Manual::NonOO>
Type::Tiny in non-object-oriented code.
=back
=head1 AUTHOR
Toby Inkster E<lt>tobyink@cpan.orgE<gt>.
=head1 COPYRIGHT AND LICENCE
This software is copyright (c) 2013-2014, 2017-2023 by Toby Inkster.
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.
=head1 DISCLAIMER OF WARRANTIES
THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
=cut
|
