1Type::Coercion(3)     User Contributed Perl Documentation    Type::Coercion(3)
2
3
4

NAME

6       Type::Coercion - a set of coercions to a particular target type
7       constraint
8

STATUS

10       This module is covered by the Type-Tiny stability policy.
11

DESCRIPTION

13   Constructors
14       "new(%attributes)"
15           Moose-style constructor function.
16
17       "add($c1, $c2)"
18           Create a Type::Coercion from two existing Type::Coercion objects.
19
20   Attributes
21       Attributes are named values that may be passed to the constructor. For
22       each attribute, there is a corresponding reader method. For example:
23
24          my $c = Type::Coercion->new( type_constraint => Int );
25          my $t = $c->type_constraint;  # Int
26
27       Important attributes
28
29       These are the attributes you are likely to be most interested in
30       providing when creating your own type coercions, and most interested in
31       reading when dealing with coercion objects.
32
33       "type_constraint"
34           Weak reference to the target type constraint (i.e. the type
35           constraint which the output of coercion coderefs is expected to
36           conform to).
37
38       "type_coercion_map"
39           Arrayref of source-type/code pairs.
40
41       "frozen"
42           Boolean; default false. A frozen coercion cannot have
43           "add_type_coercions" called upon it.
44
45       "name"
46           A name for the coercion. These need to conform to certain naming
47           rules (they must begin with an uppercase letter and continue using
48           only letters, digits 0-9 and underscores).
49
50           Optional; if not supplied will be an anonymous coercion.
51
52       "display_name"
53           A name to display for the coercion when stringified. These don't
54           have to conform to any naming rules. Optional; a default name will
55           be calculated from the "name".
56
57       "library"
58           The package name of the type library this coercion is associated
59           with.  Optional. Informational only: setting this attribute does
60           not install the coercion into the package.
61
62       Attributes related to parameterizable and parameterized coercions
63
64       The following attributes are used for parameterized coercions, but are
65       not fully documented because they may change in the near future:
66
67       "coercion_generator"
68       "parameters"
69       "parameterized_from"
70
71       Lazy generated attributes
72
73       The following attributes should not be usually passed to the
74       constructor; unless you're doing something especially unusual, you
75       should rely on the default lazily-built return values.
76
77       "compiled_coercion"
78           Coderef to coerce a value ($_[0]).
79
80           The general point of this attribute is that you should not set it,
81           but rely on the lazily-built default. Type::Coerce will usually
82           generate a pretty fast coderef, inlining all type constraint
83           checks, etc.
84
85       "moose_coercion"
86           A Moose::Meta::TypeCoercion object equivalent to this one. Don't
87           set this manually; rely on the default built one.
88
89   Methods
90       Predicate methods
91
92       These methods return booleans indicating information about the
93       coercion.  They are each tightly associated with a particular
94       attribute.  (See "Attributes".)
95
96       "has_type_constraint", "has_library"
97           Simple Moose-style predicate methods indicating the presence or
98           absence of an attribute.
99
100       "is_anon"
101           Returns true iff the coercion does not have a "name".
102
103       The following predicates are used for parameterized coercions, but are
104       not fully documented because they may change in the near future:
105
106       "has_coercion_generator"
107       "has_parameters"
108       "is_parameterizable"
109       "is_parameterized"
110
111       Coercion
112
113       The following methods are used for coercing values to a type
114       constraint:
115
116       "coerce($value)"
117           Coerce the value to the target type.
118
119           Returns the coerced value, or the original value if no coercion was
120           possible.
121
122       "assert_coerce($value)"
123           Coerce the value to the target type, and throw an exception if the
124           result does not validate against the target type constraint.
125
126           Returns the coerced value.
127
128       Coercion code definition methods
129
130       These methods all return $self so are suitable for chaining.
131
132       "add_type_coercions($type1, $code1, ...)"
133           Takes one or more pairs of Type::Tiny constraints and coercion
134           code, creating an ordered list of source types and coercion codes.
135
136           Coercion codes can be expressed as either a string of Perl code
137           (this includes objects which overload stringification), or a
138           coderef (or object that overloads coderefification). In either
139           case, the value to be coerced is $_.
140
141           "add_type_coercions($coercion_object)" also works, and can be used
142           to copy coercions from another type constraint:
143
144              $type->coercion->add_type_coercions($othertype->coercion)->freeze;
145
146       "freeze"
147           Sets the "frozen" attribute to true. Called automatically by
148           Type::Tiny sometimes.
149
150       "i_really_want_to_unfreeze"
151           If you really want to unfreeze a coercion, call this method.
152
153           Don't call this method. It will potentially lead to subtle bugs.
154
155           This method is considered unstable; future versions of Type::Tiny
156           may alter its behaviour (e.g. to throw an exception if it has been
157           detected that unfreezing this particular coercion will cause bugs).
158
159       Parameterization
160
161       The following method is used for parameterized coercions, but is not
162       fully documented because it may change in the near future:
163
164       "parameterize(@params)"
165
166       Type coercion introspection methods
167
168       These methods allow you to determine a coercion's relationship to type
169       constraints:
170
171       "has_coercion_for_type($source_type)"
172           Returns true iff this coercion has a coercion from the source type.
173
174           Returns the special string "0 but true" if no coercion should
175           actually be necessary for this type. (For example, if a coercion
176           coerces to a theoretical "Number" type, there is probably no
177           coercion necessary for values that already conform to the "Integer"
178           type.)
179
180       "has_coercion_for_value($value)"
181           Returns true iff the value could be coerced by this coercion.
182
183           Returns the special string "0 but true" if no coercion would be
184           actually be necessary for this value (due to it already meeting the
185           target type constraint).
186
187       The "type_constraint" attribute provides a type constraint object for
188       the target type constraint of the coercion. See "Attributes".
189
190       Inlining methods
191
192       The following methods are used to generate strings of Perl code which
193       may be pasted into stringy "eval"uated subs to perform type coercions:
194
195       "can_be_inlined"
196           Returns true iff the coercion can be inlined.
197
198       "inline_coercion($varname)"
199           Much like "inline_coerce" from Type::Tiny.
200
201       Other methods
202
203       "qualified_name"
204           For non-anonymous coercions that have a library, returns a
205           qualified "MyLib::MyCoercion" sort of name. Otherwise, returns the
206           same as "name".
207
208       "isa($class)", "can($method)", "AUTOLOAD(@args)"
209           If Moose is loaded, then the combination of these methods is used
210           to mock a Moose::Meta::TypeCoercion.
211
212       The following methods exist for Moose/Mouse compatibility, but do not
213       do anything useful.
214
215       "compile_type_coercion"
216       "meta"
217
218   Overloading
219       •   Boolification is overloaded to always return true.
220
221       •   Coderefification is overloaded to call "coerce".
222
223       •   On Perl 5.10.1 and above, smart match is overloaded to call
224           "has_coercion_for_value".
225
226       Previous versions of Type::Coercion would overload the "+" operator to
227       call "add". Support for this was dropped after 0.040.
228

DIAGNOSTICS

230       Attempt to add coercion code to a Type::Coercion which has been frozen
231           Type::Tiny type constraints are designed as immutable objects. Once
232           you've created a constraint, rather than modifying it you generally
233           create child constraints to do what you need.
234
235           Type::Coercion objects, on the other hand, are mutable. Coercion
236           routines can be added at any time during the object's lifetime.
237
238           Sometimes Type::Tiny needs to freeze a Type::Coercion object to
239           prevent this.  In Moose and Mouse code this is likely to happen as
240           soon as you use a type constraint in an attribute.
241
242           Workarounds:
243
244           •   Define as many of your coercions as possible within type
245               libraries, not within the code that uses the type libraries.
246               The type library will be evaluated relatively early, likely
247               before there is any reason to freeze a coercion.
248
249           •   If you do need to add coercions to a type within application
250               code outside the type library, instead create a subtype and add
251               coercions to that. The "plus_coercions" method provided by
252               Type::Tiny should make this simple.
253

BUGS

255       Please report any bugs to
256       <https://github.com/tobyink/p5-type-tiny/issues>.
257

SEE ALSO

259       Type::Tiny::Manual.
260
261       Type::Tiny, Type::Library, Type::Utils, Types::Standard.
262
263       Type::Coercion::Union.
264
265       Moose::Meta::TypeCoercion.
266

AUTHOR

268       Toby Inkster <tobyink@cpan.org>.
269
271       This software is copyright (c) 2013-2014, 2017-2021 by Toby Inkster.
272
273       This is free software; you can redistribute it and/or modify it under
274       the same terms as the Perl 5 programming language system itself.
275

DISCLAIMER OF WARRANTIES

277       THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
278       WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
279       MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
280
281
282
283perl v5.34.0                      2021-09-13                 Type::Coercion(3)
Impressum