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 or two:

      $maybe_an_object->$_call_if_object(name => @args);
      $maybe_an_object->$_call_if_can(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.

    We are careful to make sure that scalar/list context is preserved for
    the method that is eventually called.

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. If the "does" method does not exist, returns
    nothing rather than failing.

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

    If called on an object, calls "DOES" on it and returns the result,
    otherwise returns nothing. On perl versions prior to 5.10.0, the built
    in core "DOES" method doesn't exist. If the method doesn't exist, this
    will fall back to calling "isa" just like the core "DOES" method.

  $_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.

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

    If called on an object, calls "can" on it; if that returns true, then
    calls "method_name" on it and returns the result; if any condition is
    false returns nothing.

SEE ALSO
    I gave a lightning talk on this module (and curry and Import::Into) at
    YAPC::NA 2013 <https://www.youtube.com/watch?v=wFXWV2yY7gE&t=46m05s>.

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.