lib/Safe/Isa.pm

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