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

