/usr/share/perl5/Type/Tiny/Manual/Coercions.pod is in libtype-tiny-perl 1.002001-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
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 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 | =pod
=encoding utf-8
=for stopwords zen
=head1 NAME
Type::Tiny::Manual::Coercions - adding coercions to type constraints
=head1 DESCRIPTION
B<< Stop! Don't do it! >>
OK, it's fairly common practice in L<Moose>/L<Mouse> code to define
coercions for type constraints. For example, suppose we have a type
constraint:
class_type PathTiny, { class => "Path::Tiny" };
We may wish to define a coercion (i.e. a conversion routine) to handle
strings, and convert them into Path::Tiny objects:
coerce PathTiny,
from Str, via { "Path::Tiny"->new($_) };
However, there are good reasons to avoid this practice. It ties the
coercion routine to the type constraint. Any people wishing to use your
C<PathTiny> type constraint need to buy in to your idea of how they
should be coerced from C<Str>. With L<Path::Tiny> this is unlikely to
be controversial, however consider:
coerce ArrayRef,
from Str, via { [split /\n/] };
In one part of the application (dealing with parsing log files for
instance), this could be legitimate. But another part (dealing with
logins perhaps) might prefer to split on colons. Another (dealing with
web services) might attempt to parse the string as a JSON array.
If all these coercions have attached themselves to the C<ArrayRef>
type constraint, coercing a string becomes a complicated proposition!
In a large application where coercions are defined across many different
files, the application can start to suffer from "spooky action at a
distance".
In the interests of Moose-compatibility, L<Type::Tiny> and L<Type::Coercion>
do allow you to define coercions this way, but they also provide an
alternative that you should consider: C<plus_coercions>.
=head2 plus_coercions
L<Type::Tiny> offers a method C<plus_coercions> which constructs a new
anonymous type constraint, but with additional coercions.
In our earlier example, we'd define the C<PathTiny> type constraint
as before:
class_type PathTiny, { class => "Path::Tiny" };
But then not define any coercions for it. Later, when using the
type constraint, we can add coercions:
my $ConfigFileType = PathTiny->plus_coercions(
Str, sub { "Path::Tiny"->new($_) },
Undef, sub { "Path::Tiny"->new("/etc/myapp/default.conf") },
);
has config_file => (
is => "ro",
isa => $ConfigFileType,
coerce => 1,
);
Where the C<PathTiny> constraint is used in another part of the code, it
will not see these coercions, because they were added to the new anonymous
type constraint, not to the C<PathTiny> constraint itself!
=head2 Named Coercions
A type library may define a named set of coercions to a particular
type. For example, let's define that coercion from C<Str> to C<ArrayRef>:
declare_coercion "LinesFromStr",
to_type ArrayRef,
from Str, q{ [split /\n/] };
Now we can import that coercion using a name, and it makes our code
look a little cleaner:
use Types::Standard qw(ArrayRef);
use MyApp::Types qw(LinesFromStr);
has lines => (
is => "ro",
isa => ArrayRef->plus_coercions(LinesFromStr),
coerce => 1,
);
=head2 Parameterized Coercions
Parameterized type constraints are familiar from Moose. For example, an
arrayref of integers:
ArrayRef[Int]
L<Type::Coercion> supports parameterized named coercions too. For example,
the following type constraint has a coercion from strings that splits them
into lines:
use Types::Standard qw( ArrayRef Split );
my $ArrayOfLines = ArrayRef->plus_coercions( Split[ qr{\n} ] );
Viewing the source code for L<Types::Standard> should give you hints as
to how they are implemented.
=head2 plus_fallback_coercions, minus_coercions and no_coercions
Getting back to the C<plus_coercions> method, there are some other
methods that perform coercion maths.
C<plus_fallback_coercions> is the same as C<plus_coercions> but the
added coercions have a lower priority than any existing coercions.
C<minus_coercions> can be given a list of type constraints that we
wish to ignore coercions for. Imagine our C<PathTiny> constraint already
has a coercion from C<Str>, then the following creates a new anonymous
type constraint without that coercion:
PathTiny->minus_coercions(Str)
C<no_coercions> gives us a new type anonymous constraint without any
of its parents coercions. This is useful as a way to create a blank slate
for a subsequent C<plus_coercions>:
PathTiny->no_coercions->plus_coercions(...)
=head2 plus_constructors
The C<plus_constructors> method defined in L<Type::Tiny::Class> is sugar
for C<plus_coercions>. The following two are the same:
PathTiny->plus_coercions(Str, q{ Path::Tiny->new($_) })
PathTiny->plus_constructors(Str, "new");
=head2 "Deep" Coercions
Certain parameterized type constraints can automatically acquire coercions
if their parameters have coercions. For example:
ArrayRef[ Int->plus_coercions(Num, q{int($_)}) ]
... does what you mean!
The parameterized type constraints that do this magic include the following
ones from L<Types::Standard>:
=over
=item *
C<ScalarRef>
=item *
C<ArrayRef>
=item *
C<HashRef>
=item *
C<Map>
=item *
C<Tuple>
=item *
C<Dict>
=item *
C<Optional>
=item *
C<Maybe>
=back
Imagine we're declaring a type library:
declare Paths, as ArrayRef[PathTiny];
The C<PathTiny> type (declared earlier in the tutorial) has a coercion
from C<Str>, so C<Paths> should be able to coerce from an arrayref of
strings, right?
B<< Wrong! >> C<< ArrayRef[PathTiny] >> can coerce from an arrayref of
strings, but C<Paths> is a separate type constraint which, although it
inherits from C<< ArrayRef[PathTiny] >> has its own (currently empty)
set of coercions.
Because that is often not what you want, Type::Tiny provides a shortcut
when declaring a subtype to copy the parent type constraint's coercions:
declare Paths, as ArrayRef[PathTiny], coercion => 1;
Now C<Paths> can coerce from an arrayref of strings.
=head3 Deep Caveat
Currently there exists ill-defined behaviour resulting from mixing deep
coercions and mutable (non-frozen) coercions. Consider the following:
class_type PathTiny, { class => "Path::Tiny" };
coerce PathTiny,
from Str, via { "Path::Tiny"->new($_) };
declare Paths, as ArrayRef[PathTiny], coercion => 1;
coerce PathTiny,
from InstanceOf["My::File"], via { $_->get_path };
An arrayref of strings can now be coerced to an arrayref of Path::Tiny
objects, but is it also now possible to coerce an arrayref of My::File
objects to an arrayref of Path::Tiny objects?
Currently the answer is "no", but this is mostly down to implementation
details. It's not clear what the best way to behave in this situation
is, and it could start working at some point in the future.
You should avoid falling into this trap by following the advice found
under L</"The (Lack of) Zen of Coercions">.
=head2 Chained Coercions
Consider the following type library:
{
package Types::Geometric;
use Type::Library -base, -declare => qw(
VectorArray
VectorArray3D
Point
Point3D
);
use Type::Utils;
use Types::Standard qw( Num Tuple InstanceOf );
declare VectorArray,
as Tuple[Num, Num];
declare VectorArray3D,
as Tuple[Num, Num, Num];
coerce VectorArray3D,
from VectorArray, via {
[ @$_, 0 ];
};
class_type Point, { class => "Point" };
coerce Point,
from VectorArray, via {
Point->new(x => $_->[0], y => $_->[1]);
};
class_type Point3D, { class => "Point3D" };
coerce Point3D,
from VectorArray3D, via {
Point3D->new(x => $_->[0], y => $_->[1], z => $_->[2]);
},
from Point, via {
Point3D->new(x => $_->x, y => $_->y, z => 0);
};
}
Given an arrayref C<< [1, 1] >> you might reasonably expect it to be
coercible to a C<Point3D> object; it matches the type constraint
C<VectorArray> so can be coerced to C<VectorArray3D> and thus to
C<Point3D>.
However, L<Type::Coercion> does not automatically chain coercions
like this. Firstly, it would be incompatible with Moose's type coercion
system which does not chain coercions. Secondly, it's ambiguous; in our
example, the arrayref could be coerced along two different paths (via
C<VectorArray3D> or via C<Point>); in this case the end result would be
the same, but in other cases it might not. Thirdly, it runs the risk of
accidentally creating loops.
Doing the chaining manually though is pretty simple. Firstly, we'll
take note of the C<coercibles> method in L<Type::Tiny>. This method
called as C<< VectorArray3D->coercibles >> returns a type constraint
meaning "anything that can be coerced to a C<VectorArray3D>".
So we can define the coercions for C<Point3D> as:
coerce Point3D,
from VectorArray3D->coercibles, via {
my $tmp = to_VectorArray3D($_);
Point3D->new(x => $tmp->[0], y => $tmp->[1], z => $tmp->[2]);
},
from Point, via {
Point3D->new(x => $_->x, y => $_->y, z => 0);
};
... and now coercing from C<< [1, 1] >> will work.
=head2 The (Lack of) Zen of Coercions
Coercions can lead to ugliness.
Let's say we define a type constraint C<Path> which has a coercion from
C<Str>. Now we define a class which uses that type constraint.
Now in another class, we define a coercion from C<ArrayRef> to C<Path>.
This kind of action at a distance is not really desirable. And in fact,
things will probably subtly break - the first class may have already
built a constructor inlining a bunch of code from the coercion.
However, you too can achieve coercion zen by following these
L<three weird tricks|http://www.slate.com/articles/business/moneybox/2013/07/how_one_weird_trick_conquered_the_internet_what_happens_when_you_click_on.html>:
=over
=item 1.
If you want to define coercions for a type, do it I<< within your type
constraint library >>, so the coercions are all defined before the
type constraint is ever used.
=item 2.
At the end of your type constraint library, consider calling
C<< $type->coercion->freeze >> on each type constraint that has a
coercion. This makes the type's coercions immutable. If anybody wants
to define any additional coercions, they'll have to create a child type
to do it with.
A shortcut exists for this:
__PACKAGE__->meta->make_immutable;
=item 3.
Use C<plus_coercions> and similar methods to easily create a child
type constraint of any existing type, and add more coercions to it.
Don't fiddle directly with the existing type constraint which may be
being used elsewhere.
Note that these methods all return type constraint objects with
frozen (immutable) coercions.
=back
That's it.
=head1 SEE ALSO
L<Moose::Manual::BestPractices>,
L<http://www.catalyzed.org/2009/06/keeping-your-coercions-to-yourself.html>.
=head1 AUTHOR
Toby Inkster E<lt>tobyink@cpan.orgE<gt>.
=head1 COPYRIGHT AND LICENCE
This software is copyright (c) 2013-2014, 2017 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
|