.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Specio::Coercion 3pm"
.TH Specio::Coercion 3pm "2021-01-31" "perl v5.32.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Specio::Coercion \- A class representing a coercion from one type to another
.SH "VERSION"
.IX Header "VERSION"
version 0.47
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    my $coercion = $type\->coercion_from_type(\*(AqInt\*(Aq);
\&
\&    my $new_value = $coercion\->coerce_value(42);
\&
\&    if ( $coercion\->can_be_inlined() ) {
\&        my $code = $coercion\->inline_coercion(\*(Aq$_[0]\*(Aq);
\&    }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This class represents a coercion from one type to another. Internally, a
coercion is a piece of code that takes a value of one type returns a new value
of a new type. For example, a coercion from c<Num> to \f(CW\*(C`Int\*(C'\fR might round a
number to its nearest integer and return that integer.
.PP
Coercions can be implemented either as a simple subroutine reference or as an
inline generator subroutine. Using an inline generator is faster but more
complicated.
.SH "API"
.IX Header "API"
This class provides the following methods.
.SS "Specio::Coercion\->new( ... )"
.IX Subsection "Specio::Coercion->new( ... )"
This method creates a new coercion object. It accepts the following named
parameters:
.IP "\(bu" 4
from => \f(CW$type\fR
.Sp
The type this coercion is from. The type must be an object which does the
Specio::Constraint::Role::Interface interface.
.Sp
This parameter is required.
.IP "\(bu" 4
to => \f(CW$type\fR
.Sp
The type this coercion is to. The type must be an object which does the
Specio::Constraint::Role::Interface interface.
.Sp
This parameter is required.
.IP "\(bu" 4
coercion => sub { ... }
.Sp
A subroutine reference implementing the coercion. It will be called as a method
on the object and passed a single argument, the value to coerce.
.Sp
It should return the new value.
.Sp
This parameter is mutually exclusive with \f(CW\*(C`inline_generator\*(C'\fR.
.Sp
Either this parameter or the \f(CW\*(C`inline_generator\*(C'\fR parameter is required.
.Sp
You can also pass this option with the key \f(CW\*(C`using\*(C'\fR in the parameter list.
.IP "\(bu" 4
inline_generator => sub { ... }
.Sp
This should be a subroutine reference which returns a string containing a
single term. This code should \fInot\fR end in a semicolon. This code should
implement the coercion.
.Sp
The generator will be called as a method on the coercion with a single
argument. That argument is the name of the variable being coerced, something
like \f(CW\*(Aq$_[0]\*(Aq\fR or \f(CW\*(Aq$var\*(Aq\fR.
.Sp
This parameter is mutually exclusive with \f(CW\*(C`coercion\*(C'\fR.
.Sp
Either this parameter or the \f(CW\*(C`coercion\*(C'\fR parameter is required.
.Sp
You can also pass this option with the key \f(CW\*(C`inline\*(C'\fR in the parameter list.
.IP "\(bu" 4
inline_environment => {}
.Sp
This should be a hash reference of variable names (with sigils) and values for
that variable. The values should be \fIreferences\fR to the values of the
variables.
.Sp
This environment will be used when compiling the coercion as part of a
subroutine. The named variables will be captured as closures in the generated
subroutine, using Eval::Closure.
.Sp
It should be very rare to need to set this in the constructor. It's more likely
that a special coercion subclass would need to provide values that it generates
internally.
.Sp
This parameter defaults to an empty hash reference.
.IP "\(bu" 4
declared_at => \f(CW$declared_at\fR
.Sp
This parameter must be a Specio::DeclaredAt object.
.Sp
This parameter is required.
.ie n .SS "$coercion\->\fBfrom()\fP, $coercion\->\fBto()\fP, $coercion\->\fBdeclared_at()\fP"
.el .SS "\f(CW$coercion\fP\->\fBfrom()\fP, \f(CW$coercion\fP\->\fBto()\fP, \f(CW$coercion\fP\->\fBdeclared_at()\fP"
.IX Subsection "$coercion->from(), $coercion->to(), $coercion->declared_at()"
These methods are all read-only attribute accessors for the corresponding
attribute.
.ie n .SS "$coercion\->description"
.el .SS "\f(CW$coercion\fP\->description"
.IX Subsection "$coercion->description"
This returns a string describing the coercion. This includes the names of the
to and from type and where the coercion was declared, so you end up with
something like \f(CW\*(Aqcoercion from Foo to Bar declared in package My::Lib
(lib/My/Lib.pm) at line 42\*(Aq\fR.
.ie n .SS "$coercion\->coerce($value)"
.el .SS "\f(CW$coercion\fP\->coerce($value)"
.IX Subsection "$coercion->coerce($value)"
Given a value of the right \*(L"from\*(R" type, returns a new value of the \*(L"to\*(R" type.
.PP
This method does not actually check that the types of given or return values.
.ie n .SS "$coercion\->inline_coercion($var)"
.el .SS "\f(CW$coercion\fP\->inline_coercion($var)"
.IX Subsection "$coercion->inline_coercion($var)"
Given a variable name like \f(CW\*(Aq$_[0]\*(Aq\fR this returns a string with code for the
coercion.
.PP
Note that this method will die if the coercion does not have an inline
generator.
.ie n .SS "$coercion\->\fBcan_be_inlined()\fP"
.el .SS "\f(CW$coercion\fP\->\fBcan_be_inlined()\fP"
.IX Subsection "$coercion->can_be_inlined()"
This returns true if the coercion has an inline generator \fIand\fR the constraint
it is from can be inlined. This exists primarily for the benefit of the
\&\f(CW\*(C`inline_coercion_and_check()\*(C'\fR method for type constraint object.
.ie n .SS "$coercion\->\fBinline_environment()\fP"
.el .SS "\f(CW$coercion\fP\->\fBinline_environment()\fP"
.IX Subsection "$coercion->inline_environment()"
This returns a hash defining the variables that need to be closed over when
inlining the coercion. The keys are full variable names like \f(CW\*(Aq$foo\*(Aq\fR or
\&\f(CW\*(Aq@bar\*(Aq\fR. The values are \fIreferences\fR to a variable of the matching type.
.ie n .SS "$coercion\->\fBclone()\fP"
.el .SS "\f(CW$coercion\fP\->\fBclone()\fP"
.IX Subsection "$coercion->clone()"
Returns a clone of this object.
.ie n .SS "$coercion\->clone_with_new_to($new_to_type)"
.el .SS "\f(CW$coercion\fP\->clone_with_new_to($new_to_type)"
.IX Subsection "$coercion->clone_with_new_to($new_to_type)"
This returns a clone of the coercion, replacing the \*(L"to\*(R" type with a new one.
This is intended for use when the to type itself is being cloned as part of
importing that type. We need to make sure the newly cloned coercion has the
newly cloned type as well.
.SH "ROLES"
.IX Header "ROLES"
This class does the Specio::Role::Inlinable role.
.SH "SUPPORT"
.IX Header "SUPPORT"
Bugs may be submitted at <https://github.com/houseabsolute/Specio/issues>.
.PP
I am also usually active on \s-1IRC\s0 as 'autarch' on \f(CW\*(C`irc://irc.perl.org\*(C'\fR.
.SH "SOURCE"
.IX Header "SOURCE"
The source code repository for Specio can be found at <https://github.com/houseabsolute/Specio>.
.SH "AUTHOR"
.IX Header "AUTHOR"
Dave Rolsky <autarch@urth.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is Copyright (c) 2012 \- 2021 by Dave Rolsky.
.PP
This is free software, licensed under:
.PP
.Vb 1
\&  The Artistic License 2.0 (GPL Compatible)
.Ve
.PP
The full text of the license can be found in the
\&\fI\s-1LICENSE\s0\fR file included with this distribution.