What is Coercion

The overload pragma, and its string overloading is the form of coercion you are most likely to have encountered in Perl programming. In this case, your object is automatically (within perl itself) coerced into a string.

"Params::Coerce" is intended for higher-order coercion between various types of different objects, for use mainly in subroutine and (mostly) method parameters, particularly on external APIs.

__as_Another_Class Methods

The preferred mechanism for this is by creating a specially named method in a class that indicates it can be coerced into another type of object.

As an example, HTML::Location provides an object method that returns an equivalent URI object.

  # In the package HTML::Location

  # Coerce to a URI
  sub __as_URI {
        my $self = shift;
        return URI->new( $self->uri );
  }

__from_Another_Class Methods

  # In the package URI

  # Coerce from a HTML::Location
  sub __from_HTML_Location {
        my $Location = shift;
        return URI->new( $Location->uri );
  }

"Params::Coerce" will only look for the __from method, if it does not find a __as method.

Loading Classes

In the above example, HTML::Location does not have to load the URI class. The need to load the classes for every object we might some day need to be coerced to would result in highly excessive resource usage.

Instead, "Params::Coerce" guarantees that the class you are converting to "will" be loaded before it calls the __as_Another_Class method. Of course, in most situations you will have already loaded it for another purpose in either the From or To classes and this won't be an issue.

If you make use of some class other than the class you are being coerced to in the __as_Another_Class method, you will need to make sure that is loaded in your code, but it is suggested that you do it at run-time with a "require" if you are not using it already elsewhere.

Coercing a Parameter

  package My::Class;

  use URI ();
  use Params::Coerce '_URI' => 'URI';

  sub new {
        my $class = shift;

        # Take a URI argument
        my $URI = Params::Coerce::coerce('URI', shift) or return;

        ...
  }

For people doing procedural programming, you may also import this function.

  # Import the coerce function
  use Params::Coerce 'coerce';

Please note that the "coerce" function is the only function that can be imported, and that the two argument pragma (or the passing of two or more arguments to ->import) means something different entirely.

Importing Parameter Coercion Methods

  package My::Class;

  use URI ();
  use Params::Coerce '_URI' => 'URI';

  sub new {
        my $class = shift;

        # Take a URI as parameter
        my $URI1 = $class->_URI(shift) or return;
        my $URI2 = _URI(shift) or return;
        ...
  }

The "from" Constructor

  package My::Class;

  use Params::Coerce 'from';

  package Other::Class;

  sub method {
        my $self = shift;
        my $My   = My::Class->from(shift) or die "Bad param";
        ...
  }

This is mainly a convenience. The above is equivalent to

  package My::Class;

  use Params::Coerce 'from' => 'Params::Coerce';

In future versions, this "->from" syntax may also tweak the resolution order of the coercion.

Chained Coercion

coerce $class, $param

Please note that it is the responsibility of the consuming class to ensure that the class you wish to coerce to is loaded. "coerce" will check this and die is it is not loaded.

Returns an instance of the class you specify, or one of its subclasses. Returns "undef" if the parameter cannot be coerced into the class you wish.