Safe::Isa(3)

💖 NAME 💖

okay so this is the Safe::Isa(3) page from the User Contributed Perl Documentation corner of Perl land, bestie — and it's about Safe::Isa: call isa, can, does and DOES safely on things that may not be objects ✨

---

✨ SYNOPSIS ✨

here's the whole vibe in code, no cap:

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

same energy for role checks, because $_does and $_DOES are literally right there:

$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 a method or two got missed, this is the moment:

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

or, reusing that earlier example for explication purposes — yes, that word — it looks like this:

$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 been out here writing:

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

and then, like, five seconds later you're cursing and changing it to:

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

right?? that's literally why this module exists. periodt 💅

so here's the iconic mechanism: perl lets us provide a subroutine reference or a method name to the -> operator when it's used as a method call, and a subroutine doesn't require the invocant to actually be an object. that means 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 👑

and we are careful to make sure that scalar/list context is preserved for the method that is eventually called. that part is non-negotiable, bestie ✨

---

🎀 EXPORTS 🎀

here's what you get, and yes, they all ate:

🌸 $_isa 🌸

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

if it's called on an object, it calls isa on it and returns the result; otherwise it returns nothing 🫶

🌺 $_can 🌺

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

if it's called on an object, it calls can on it and returns the result; otherwise it returns nothing 💖

🦋 $_does 🦋

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

if it's called on an object, it calls does on it and returns the result; otherwise it returns nothing. and if the does method does not exist, it returns nothing rather than failing — no dramatic meltdown today, thanks 😌

💅 $_DOES 💅

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

if it's called on an object, it calls DOES on it and returns the result; otherwise it returns nothing. important caveat: 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 it's called on an object, it calls method_name on it and returns the result; otherwise it returns nothing. iconic behavior, honestly ⭐

⭐ $_call_if_can ⭐

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

if it's called on an object, it calls can on it; if that returns true, then it calls method_name on it and returns the result; if any condition is false, it returns nothing. vibe check passed 🫶

---

🌈 SEE ALSO 🌈

the author gave a lightning talk on this module (and curry and Import::Into) at YAPC::NA 2013 — video URL: 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. slay 💅

---

mwah 💋 — this page is from perl v5.42.0, dated 2018-04-26. bye bestie, go be safe with your method calls ✨🫶