Specio::Coercion - phpMan

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 AT 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.