/ 
Safe-Isa-1.000005
River stage four • 89 direct dependents • 1346 total dependents
/ Safe::Isa

NAME

Safe::Isa - Call isa, can, does and DOES safely on things that may not be objects

SYNOPSIS

use strict;
use warnings;

{ package Foo; sub new { bless({}, $_[0]) } }
{ package Bar; our @ISA = qw(Foo); sub bar { 1 } }

my $foo = Foo->new;
my $bar = Bar->new;
my $blam = [ 42 ];

# basic isa usage -

$foo->isa('Foo');  # true
$bar->isa('Foo');  # true
$blam->isa('Foo'); # BOOM

$foo->can('bar');  # false
$bar->can('bar');  # true
$blam->can('bar'); # BOOM

# Safe::Isa usage -

use Safe::Isa;

$foo->$_isa('Foo');  # true
$bar->$_isa('Foo');  # true
$blam->$_isa('Foo'); # false, no boom today

$foo->$_can('bar');  # false
$bar->$_can('bar');  # true
$blam->$_can('bar'); # false, no boom today

Similarly:

$maybe_an_object->$_does('RoleName'); # true or false, no boom today
$maybe_an_object->$_DOES('RoleName'); # true or false, no boom today

And just in case we missed a method:

$maybe_an_object->$_call_if_object(name => @args);

Or to re-use a previous example for purposes of explication:

$foo->$_call_if_object(isa => 'Foo');  # true
$bar->$_call_if_object(isa => 'Foo');  # true
$blam->$_call_if_object(isa => 'Foo'); # false, no boom today

DESCRIPTION

How many times have you found yourself writing:

if ($obj->isa('Something')) {

and then shortly afterwards cursing and changing it to:

if (Scalar::Util::blessed($obj) and $obj->isa('Something')) {

Right. That's why this module exists.

Since perl allows us to provide a subroutine reference or a method name to the -> operator when used as a method call, and a subroutine doesn't require the invocant to actually be an object, we can create safe versions of isa, can and friends by using a subroutine reference that only tries to call the method if it's used on an object. So:

my $isa_Foo = $maybe_an_object->$_call_if_object(isa => 'Foo');

is equivalent to

my $isa_Foo = do {
  if (Scalar::Util::blessed($maybe_an_object)) {
    $maybe_an_object->isa('Foo');
  } else {
    undef;
  }
};

Note that we don't handle trying class names, because many things are valid class names that you might not want to treat as one (like say "Matt") - the is_module_name function from Module::Runtime is a good way to check for something you might be able to call methods on if you want to do that.

EXPORTS

$_isa

$maybe_an_object->$_isa('Foo');

If called on an object, calls isa on it and returns the result, otherwise returns nothing.

$_can

$maybe_an_object->$_can('Foo');

If called on an object, calls can on it and returns the result, otherwise returns nothing.

$_does

$maybe_an_object->$_does('Foo');

If called on an object, calls does on it and returns the result, otherwise returns nothing.

$_DOES

$maybe_an_object->$_DOES('Foo');

If called on an object, calls DOES on it and returns the result, otherwise returns nothing.

$_call_if_object

$maybe_an_object->$_call_if_object(method_name => @args);

If called on an object, calls method_name on it and returns the result, otherwise returns nothing.

SEE ALSO

I gave a lightning talk on this module (and curry and Import::Into) at YAPC::NA 2013.

AUTHOR

mst - Matt S. Trout (cpan:MSTROUT) <mst@shadowcat.co.uk>

CONTRIBUTORS

None yet. Well volunteered? :)

COPYRIGHT

Copyright (c) 2012 the Safe::Isa "AUTHOR" and "CONTRIBUTORS" as listed above.

LICENSE

This library is free software and may be distributed under the same terms as perl itself.