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.

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.