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

NAME

6       Specio::Coercion - A class representing a coercion from one type to
7       another
8

VERSION

10       version 0.47
11

SYNOPSIS

13           my $coercion = $type->coercion_from_type('Int');
14
15           my $new_value = $coercion->coerce_value(42);
16
17           if ( $coercion->can_be_inlined() ) {
18               my $code = $coercion->inline_coercion('$_[0]');
19           }
20

DESCRIPTION

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
27       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

API

32       This class provides the following methods.
33
34   Specio::Coercion->new( ... )
35       This method creates a new coercion object. It accepts the following
36       named parameters:
37
38       •   from => $type
39
40           The type this coercion is from. The type must be an object which
41           does the Specio::Constraint::Role::Interface interface.
42
43           This parameter is required.
44
45       •   to => $type
46
47           The type this coercion is to. The type must be an object which does
48           the Specio::Constraint::Role::Interface interface.
49
50           This parameter is required.
51
52       •   coercion => sub { ... }
53
54           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
58           It should return the new value.
59
60           This parameter is mutually exclusive with "inline_generator".
61
62           Either this parameter or the "inline_generator" parameter is
63           required.
64
65           You can also pass this option with the key "using" in the parameter
66           list.
67
68       •   inline_generator => sub { ... }
69
70           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
74           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
78           This parameter is mutually exclusive with "coercion".
79
80           Either this parameter or the "coercion" parameter is required.
81
82           You can also pass this option with the key "inline" in the
83           parameter list.
84
85       •   inline_environment => {}
86
87           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
91           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
95           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
99           This parameter defaults to an empty hash reference.
100
101       •   declared_at => $declared_at
102
103           This parameter must be a Specio::DeclaredAt object.
104
105           This parameter is required.
106
107   $coercion->from(), $coercion->to(), $coercion->declared_at()
108       These methods are all read-only attribute accessors for the
109       corresponding attribute.
110
111   $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
117   $coercion->coerce($value)
118       Given a value of the right "from" type, returns a new value of the "to"
119       type.
120
121       This method does not actually check that the types of given or return
122       values.
123
124   $coercion->inline_coercion($var)
125       Given a variable name like '$_[0]' this returns a string with code for
126       the coercion.
127
128       Note that this method will die if the coercion does not have an inline
129       generator.
130
131   $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
137   $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
143   $coercion->clone()
144       Returns a clone of this object.
145
146   $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

ROLES

153       This class does the Specio::Role::Inlinable role.
154

SUPPORT

156       Bugs may be submitted at
157       <https://github.com/houseabsolute/Specio/issues>.
158
159       I am also usually active on IRC as 'autarch' on "irc://irc.perl.org".
160

SOURCE

162       The source code repository for Specio can be found at
163       <https://github.com/houseabsolute/Specio>.
164

AUTHOR

166       Dave Rolsky <autarch@urth.org>
167
169       This software is Copyright (c) 2012 - 2021 by Dave Rolsky.
170
171       This is free software, licensed under:
172
173         The Artistic License 2.0 (GPL Compatible)
174
175       The full text of the license can be found in the LICENSE file included
176       with this distribution.
177
178
179
180perl v5.32.1                      2021-01-31               Specio::Coercion(3)
Impressum