skip the redundant blessed call in $_call_if_can
[p5sagit/Safe-Isa.git] / lib / Safe / Isa.pm
CommitLineData
e6995dc6 1package Safe::Isa;
2
3use strict;
4use warnings FATAL => 'all';
29153068 5use Scalar::Util ();
7b1885ee 6use Exporter 5.57 qw(import);
e6995dc6 7
ad7bcdc0 8our $VERSION = '1.000007';
e6995dc6 9
ff5366db 10our @EXPORT = qw($_call_if_object $_isa $_can $_does $_DOES $_call_if_can);
e6995dc6 11
12our $_call_if_object = sub {
13 my ($obj, $method) = (shift, shift);
f3335392 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.
29153068 17 return unless Scalar::Util::blessed($obj);
de8d80ef 18 return $obj->isa(@_) if lc($method) eq 'does' and not $obj->can($method);
e6995dc6 19 return $obj->$method(@_);
20};
21
22our ($_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
ff5366db 27our $_call_if_can = sub {
28 my ($obj, $method) = (shift, shift);
fe34d000 29 $obj->$_call_if_object(can => $method) && $obj->$method(@_);
ff5366db 30};
31
b19500df 321;
33__END__
34
35=pod
36
e6995dc6 37=head1 NAME
38
39Safe::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
75Similarly:
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
ff5366db 80And just in case we missed a method or two:
e6995dc6 81
82 $maybe_an_object->$_call_if_object(name => @args);
ff5366db 83 $maybe_an_object->$_call_if_can(name => @args);
e6995dc6 84
85Or to re-use a previous example for purposes of explication:
86
ff9518c5 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
e6995dc6 90
91=head1 DESCRIPTION
92
93How many times have you found yourself writing:
94
95 if ($obj->isa('Something')) {
96
97and then shortly afterwards cursing and changing it to:
98
99 if (Scalar::Util::blessed($obj) and $obj->isa('Something')) {
100
101Right. That's why this module exists.
102
103Since perl allows us to provide a subroutine reference or a method name to
104the -> operator when used as a method call, and a subroutine doesn't require
105the invocant to actually be an object, we can create safe versions of isa,
106can and friends by using a subroutine reference that only tries to call the
107method if it's used on an object. So:
108
109 my $isa_Foo = $maybe_an_object->$_call_if_object(isa => 'Foo');
110
111is 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
fca38ff4 121Note that we don't handle trying class names, because many things are valid
122class names that you might not want to treat as one (like say "Matt") - the
123C<is_module_name> function from L<Module::Runtime> is a good way to check for
f94f3bbb 124something you might be able to call methods on if you want to do that.
fca38ff4 125
e6995dc6 126=head1 EXPORTS
127
128=head2 $_isa
129
130 $maybe_an_object->$_isa('Foo');
131
132If called on an object, calls C<isa> on it and returns the result, otherwise
133returns nothing.
134
135=head2 $_can
136
137 $maybe_an_object->$_can('Foo');
138
139If called on an object, calls C<can> on it and returns the result, otherwise
140returns nothing.
141
142=head2 $_does
143
144 $maybe_an_object->$_does('Foo');
145
146If called on an object, calls C<does> on it and returns the result, otherwise
147returns nothing.
148
149=head2 $_DOES
150
151 $maybe_an_object->$_DOES('Foo');
152
153If called on an object, calls C<DOES> on it and returns the result, otherwise
154returns nothing.
155
4703f64c 156=head2 $_call_if_object
e6995dc6 157
4703f64c 158 $maybe_an_object->$_call_if_object(method_name => @args);
e6995dc6 159
160If called on an object, calls C<method_name> on it and returns the result,
161otherwise returns nothing.
162
ff5366db 163=head2 $_call_if_can
164
165 $maybe_an_object->$_call_if_can(name => @args);
166
167If called on an object, calls C<can> on it; if that returns true, then
168calls C<method_name> on it and returns the result; if any condition is false
169returns nothing.
170
91dfd937 171=head1 SEE ALSO
172
173I gave a lightning talk on this module (and L<curry> and L<Import::Into>) at
174L<YAPC::NA 2013|https://www.youtube.com/watch?v=wFXWV2yY7gE&t=46m05s>.
175
e6995dc6 176=head1 AUTHOR
177
178mst - Matt S. Trout (cpan:MSTROUT) <mst@shadowcat.co.uk>
179
180=head1 CONTRIBUTORS
181
182None yet. Well volunteered? :)
183
184=head1 COPYRIGHT
185
186Copyright (c) 2012 the Safe::Isa L</AUTHOR> and L</CONTRIBUTORS>
187as listed above.
188
189=head1 LICENSE
190
191This library is free software and may be distributed under the same terms
192as perl itself.
193
194=cut