1Specio::Coercion(3) User Contributed Perl Documentation Specio::Coercion(3)
2
6 Specio::Coercion - A class representing a coercion from one type to
7 another
8
10 version 0.48
11
13 my $coercion = $type->coercion_from_type('Int');
14 my $new_value = $coercion->coerce_value(42);
16 if ( $coercion->can_be_inlined() ) {
18 my $code = $coercion->inline_coercion('$_[0]');
19 }
20
22 This class represents a coercion from one type to another. Internally,
23 a coercion is a piece of code that takes a value of one type returns a
24 new value of a new type. For example, a coercion from c<Num> to "Int"
25 might round a number to its nearest integer and return that integer.
26 Coercions can be implemented either as a simple subroutine reference or
28 as an inline generator subroutine. Using an inline generator is faster
29 but more complicated.
30
32 This class provides the following methods.
33 Specio::Coercion->new( ... )
35 This method creates a new coercion object. It accepts the following
36 named parameters:
37 • from => $type
39 The type this coercion is from. The type must be an object which
41 does the Specio::Constraint::Role::Interface interface.
42 This parameter is required.
44 • to => $type
46 The type this coercion is to. The type must be an object which does
48 the Specio::Constraint::Role::Interface interface.
49 This parameter is required.
51 • coercion => sub { ... }
53 A subroutine reference implementing the coercion. It will be called
55 as a method on the object and passed a single argument, the value
56 to coerce.
57 It should return the new value.
59 This parameter is mutually exclusive with "inline_generator".
61 Either this parameter or the "inline_generator" parameter is
63 required.
64 You can also pass this option with the key "using" in the parameter
66 list.
67 • inline_generator => sub { ... }
69 This should be a subroutine reference which returns a string
71 containing a single term. This code should not end in a semicolon.
72 This code should implement the coercion.
73 The generator will be called as a method on the coercion with a
75 single argument. That argument is the name of the variable being
76 coerced, something like '$_[0]' or '$var'.
77 This parameter is mutually exclusive with "coercion".
79 Either this parameter or the "coercion" parameter is required.
81 You can also pass this option with the key "inline" in the
83 parameter list.
84 • inline_environment => {}
86 This should be a hash reference of variable names (with sigils) and
88 values for that variable. The values should be references to the
89 values of the variables.
90 This environment will be used when compiling the coercion as part
92 of a subroutine. The named variables will be captured as closures
93 in the generated subroutine, using Eval::Closure.
94 It should be very rare to need to set this in the constructor. It's
96 more likely that a special coercion subclass would need to provide
97 values that it generates internally.
98 This parameter defaults to an empty hash reference.
100 • declared_at => $declared_at
102 This parameter must be a Specio::DeclaredAt object.
104 This parameter is required.
106 $coercion->from(), $coercion->to(), $coercion->declared_at()
108 These methods are all read-only attribute accessors for the
109 corresponding attribute.
110 $coercion->description
112 This returns a string describing the coercion. This includes the names
113 of the to and from type and where the coercion was declared, so you end
114 up with something like 'coercion from Foo to Bar declared in package
115 My::Lib (lib/My/Lib.pm) at line 42'.
116 $coercion->coerce($value)
118 Given a value of the right "from" type, returns a new value of the "to"
119 type.
120 This method does not actually check that the types of given or return
122 values.
123 $coercion->inline_coercion($var)
125 Given a variable name like '$_[0]' this returns a string with code for
126 the coercion.
127 Note that this method will die if the coercion does not have an inline
129 generator.
130 $coercion->can_be_inlined()
132 This returns true if the coercion has an inline generator and the
133 constraint it is from can be inlined. This exists primarily for the
134 benefit of the inline_coercion_and_check() method for type constraint
135 object.
136 $coercion->inline_environment()
138 This returns a hash defining the variables that need to be closed over
139 when inlining the coercion. The keys are full variable names like
140 '$foo' or '@bar'. The values are references to a variable of the
141 matching type.
142 $coercion->clone()
144 Returns a clone of this object.
145 $coercion->clone_with_new_to($new_to_type)
147 This returns a clone of the coercion, replacing the "to" type with a
148 new one. This is intended for use when the to type itself is being
149 cloned as part of importing that type. We need to make sure the newly
150 cloned coercion has the newly cloned type as well.
151
153 This class does the Specio::Role::Inlinable role.
154
156 Bugs may be submitted at
157 <https://github.com/houseabsolute/Specio/issues>.
158
160 The source code repository for Specio can be found at
161 <https://github.com/houseabsolute/Specio>.
162
164 Dave Rolsky <autarch@urth.org>
165
167 This software is Copyright (c) 2012 - 2022 by Dave Rolsky.
168 This is free software, licensed under:
170 The Artistic License 2.0 (GPL Compatible)
172 The full text of the license can be found in the LICENSE file included
174 with this distribution.
175perl v5.38.0 2023-07-21 Specio::Coercion(3)