lib/Safe/Isa.pm

   1 package Safe::Isa;
   2
   3 use strict;
   4 use warnings FATAL => 'all';
   5 use Scalar::Util qw(blessed);
   6 use Exporter 5.57 qw(import);
   7
   8 our $VERSION = '1.000004';
   9
  10 our @EXPORT = qw($_call_if_object $_call_if_object_or_classname $_isa $_can $_does $_DOES);
  11
  12 our $_call_if_object = sub {
  13   my ($obj, $method) = (shift, shift);
  14   return unless blessed($obj);
  15   return $obj->$method(@_);
  16 };
  17
  18 our $_call_if_object_or_classname = sub {
  19   my ($thing, $method) = (shift, shift);
  20   return unless blessed($thing) or defined($thing) and do {
  21     no strict 'refs';
  22     %{"main::${thing}::"}
  23   };
  24   return $thing->$method(@_);
  25 };
  26
  27 our ($_isa, $_can, $_does, $_DOES) = map {
  28   my $method = $_;
  29   sub { my $obj = shift; $obj->$_call_if_object_or_classname($method => @_) }
  30 } qw(isa can does DOES);
  31
  32 =head1 NAME
  33
  34 Safe::Isa - Call isa, can, does and DOES safely on arbitrary things
  35
  36 =head1 SYNOPSIS
  37
  38   use strict;
  39   use warnings;
  40
  41   { package Foo; sub new { bless({}, $_[0]) } }
  42   { package Bar; our @ISA = qw(Foo); sub bar { 1 } }
  43
  44   my $foo = Foo->new;
  45   my $bar = Bar->new;
  46   my $class = 'Bar';
  47   my $blam = [ 42 ];
  48
  49   # basic isa usage -
  50
  51   $foo->isa('Foo');  # true
  52   $bar->isa('Foo');  # true
  53   $class->isa('Foo') # true
  54   $blam->isa('Foo'); # BOOM
  55
  56   $foo->can('bar');  # false
  57   $bar->can('bar');  # true
  58   $class->can('bar); # true
  59   $blam->can('bar'); # BOOM
  60
  61   # Safe::Isa usage -
  62
  63   use Safe::Isa;
  64
  65   $foo->$_isa('Foo');  # true
  66   $bar->$_isa('Foo');  # true
  67   $class->isa('Foo')   # true
  68   $blam->$_isa('Foo'); # false, no boom today
  69
  70   $foo->$_can('bar');  # false
  71   $bar->$_can('bar');  # true
  72   $class->can('bar);   # true
  73   $blam->$_can('bar'); # false, no boom today
  74
  75 Similarly:
  76
  77   $maybe_an_object->$_does('RoleName'); # true or false, no boom today
  78   $maybe_an_object->$_DOES('RoleName'); # true or false, no boom today
  79
  80 And just in case we missed a method:
  81
  82   $maybe_an_object->$_call_if_object(name => @args);
  83
  84 or this might be closer to what you want:
  85
  86   $maybe_a_referent->$_call_if_object_or_class(name => @args);
  87
  88 Or to re-use a previous example for purposes of explication:
  89
  90   $foo->$_call_if_object(isa => 'Foo');  # true
  91   $bar->$_call_if_object(isa => 'Foo');  # true
  92   $blam->$_call_if_object(isa => 'Foo'); # false, no boom today
  93
  94 =head1 DESCRIPTION
  95
  96 How many times have you found yourself writing:
  97
  98   if ($obj->isa('Something')) {
  99
 100 and then shortly afterwards cursing and changing it to:
 101
 102   if (Scalar::Util::blessed($obj) and $obj->isa('Something')) {
 103
 104 Right. That's why this module exists.
 105
 106 Since perl allows us to provide a subroutine reference or a method name to
 107 the -> operator when used as a method call, and a subroutine doesn't require
 108 the invocant to actually be an object, we can create safe versions of isa,
 109 can and friends by using a subroutine reference that only tries to call the
 110 method if it's used on an object. So:
 111
 112   my $isa_Foo = $maybe_an_object->$_call_if_object(isa => 'Foo');
 113
 114 is equivalent to
 115
 116   my $isa_Foo = do {
 117     if (Scalar::Util::blessed($maybe_an_object)) {
 118       $maybe_an_object->isa('Foo');
 119     } else {
 120       undef;
 121     }
 122   };
 123
 124 Note that we don't handle trying class names, because many things are valid
 125 class names that you might not want to treat as one (like say "Matt") - the
 126 C<is_module_name> function from L<Module::Runtime> is a good way to check for
 127 something you might be able to call methods on if you want to do that.
 128
 129 =head1 EXPORTS
 130
 131 =head2 $_isa
 132
 133   $maybe_an_object->$_isa('Foo');
 134
 135 If called on an object, calls C<isa> on it and returns the result, otherwise
 136 returns nothing.
 137
 138 =head2 $_can
 139
 140   $maybe_an_object->$_can('Foo');
 141
 142 If called on an object, calls C<can> on it and returns the result, otherwise
 143 returns nothing.
 144
 145 =head2 $_does
 146
 147   $maybe_an_object->$_does('Foo');
 148
 149 If called on an object, calls C<does> on it and returns the result, otherwise
 150 returns nothing.
 151
 152 =head2 $_DOES
 153
 154   $maybe_an_object->$_DOES('Foo');
 155
 156 If called on an object, calls C<DOES> on it and returns the result, otherwise
 157 returns nothing.
 158
 159 =head2 $_call_if_object
 160
 161   $maybe_an_object->$_call_if_object(method_name => @args);
 162
 163 If called on an object, calls C<method_name> on it and returns the result,
 164 otherwise returns nothing.
 165
 166 =head1 AUTHOR
 167
 168 mst - Matt S. Trout (cpan:MSTROUT) <mst@shadowcat.co.uk>
 169
 170 =head1 CONTRIBUTORS
 171
 172 None yet. Well volunteered? :)
 173
 174 =head1 COPYRIGHT
 175
 176 Copyright (c) 2012 the Safe::Isa L</AUTHOR> and L</CONTRIBUTORS>
 177 as listed above.
 178
 179 =head1 LICENSE
 180
 181 This library is free software and may be distributed under the same terms
 182 as perl itself.
 183
 184 =cut