NAME

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

VERSION

       version 0.47

SYNOPSIS

           my $coercion = $type->coercion_from_type('Int');

           my $new_value = $coercion->coerce_value(42);

           if ( $coercion->can_be_inlined() ) {
               my $code = $coercion->inline_coercion('$_[0]');
           }

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 "Int"
       might round a number to its nearest integer and return that integer.

       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.

API

       This class provides the following methods.

   Specio::Coercion->new( ... )
       This method creates a new coercion object. It accepts the following named parameters:

       •   from => $type

           The type this coercion is from. The type must be an object which does the
           Specio::Constraint::Role::Interface interface.

           This parameter is required.

       •   to => $type

           The type this coercion is to. The type must be an object which does the
           Specio::Constraint::Role::Interface interface.

           This parameter is required.

       •   coercion => sub { ... }

           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.

           It should return the new value.

           This parameter is mutually exclusive with "inline_generator".

           Either this parameter or the "inline_generator" parameter is required.

           You can also pass this option with the key "using" in the parameter list.

       •   inline_generator => sub { ... }

           This should be a subroutine reference which returns a string containing a single term. This code
           should not end in a semicolon. This code should implement the coercion.

           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 '$_[0]' or '$var'.

           This parameter is mutually exclusive with "coercion".

           Either this parameter or the "coercion" parameter is required.

           You can also pass this option with the key "inline" in the parameter list.

       •   inline_environment => {}

           This should be a hash reference of variable names (with sigils) and values for that variable. The
           values should be references to the values of the variables.

           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.

           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.

           This parameter defaults to an empty hash reference.

       •   declared_at => $declared_at

           This parameter must be a Specio::DeclaredAt object.

           This parameter is required.

   $coercion->from(), $coercion->to(), $coercion->declared_at()
       These methods are all read-only attribute accessors for the corresponding attribute.

   $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 'coercion from Foo to Bar declared in
       package My::Lib (lib/My/Lib.pm) at line 42'.

   $coercion->coerce($value)
       Given a value of the right "from" type, returns a new value of the "to" type.

       This method does not actually check that the types of given or return values.

   $coercion->inline_coercion($var)
       Given a variable name like '$_[0]' this returns a string with code for the coercion.

       Note that this method will die if the coercion does not have an inline generator.

   $coercion->can_be_inlined()
       This returns true if the coercion has an inline generator and the constraint it is from can be inlined.
       This exists primarily for the benefit of the "inline_coercion_and_check()" method for type constraint
       object.

   $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 '$foo' or '@bar'. The values are references to a variable of the
       matching type.

   $coercion->clone()
       Returns a clone of this object.

   $coercion->clone_with_new_to($new_to_type)
       This returns a clone of the coercion, replacing the "to" 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.

ROLES

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

SUPPORT

       Bugs may be submitted at <https://github.com/houseabsolute/Specio/issues>.

       I am also usually active on IRC as 'autarch' on "irc://irc.perl.org".

SOURCE

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

AUTHOR

       Dave Rolsky <autarch@urth.org>

COPYRIGHT AND LICENSE

       This software is Copyright (c) 2012 - 2021 by Dave Rolsky.

       This is free software, licensed under:

         The Artistic License 2.0 (GPL Compatible)

       The full text of the license can be found in the LICENSE file included with this distribution.