README
1NAME
2 Safe::Isa - Call isa, can, does and DOES safely on things that may not
3 be objects
4
5SYNOPSIS
6 use strict;
7 use warnings;
8
9 { package Foo; sub new { bless({}, $_[0]) } }
10 { package Bar; our @ISA = qw(Foo); sub bar { 1 } }
11
12 my $foo = Foo->new;
13 my $bar = Bar->new;
14 my $blam = [ 42 ];
15
16 # basic isa usage -
17
18 $foo->isa('Foo'); # true
19 $bar->isa('Foo'); # true
20 $blam->isa('Foo'); # BOOM
21
22 $foo->can('bar'); # false
23 $bar->can('bar'); # true
24 $blam->can('bar'); # BOOM
25
26 # Safe::Isa usage -
27
28 use Safe::Isa;
29
30 $foo->$_isa('Foo'); # true
31 $bar->$_isa('Foo'); # true
32 $blam->$_isa('Foo'); # false, no boom today
33
34 $foo->$_can('bar'); # false
35 $bar->$_can('bar'); # true
36 $blam->$_can('bar'); # false, no boom today
37
38 Similarly:
39
40 $maybe_an_object->$_does('RoleName'); # true or false, no boom today
41 $maybe_an_object->$_DOES('RoleName'); # true or false, no boom today
42
43 And just in case we missed a method or two:
44
45 $maybe_an_object->$_call_if_object(name => @args);
46 $maybe_an_object->$_call_if_can(name => @args);
47
48 Or to re-use a previous example for purposes of explication:
49
50 $foo->$_call_if_object(isa => 'Foo'); # true
51 $bar->$_call_if_object(isa => 'Foo'); # true
52 $blam->$_call_if_object(isa => 'Foo'); # false, no boom today
53
54DESCRIPTION
55 How many times have you found yourself writing:
56
57 if ($obj->isa('Something')) {
58
59 and then shortly afterwards cursing and changing it to:
60
61 if (Scalar::Util::blessed($obj) and $obj->isa('Something')) {
62
63 Right. That's why this module exists.
64
65 Since perl allows us to provide a subroutine reference or a method name
66 to the -> operator when used as a method call, and a subroutine doesn't
67 require the invocant to actually be an object, we can create safe
68 versions of isa, can and friends by using a subroutine reference that
69 only tries to call the method if it's used on an object. So:
70
71 my $isa_Foo = $maybe_an_object->$_call_if_object(isa => 'Foo');
72
73 is equivalent to
74
75 my $isa_Foo = do {
76 if (Scalar::Util::blessed($maybe_an_object)) {
77 $maybe_an_object->isa('Foo');
78 } else {
79 undef;
80 }
81 };
82
83 Note that we don't handle trying class names, because many things are
84 valid class names that you might not want to treat as one (like say
85 "Matt") - the "is_module_name" function from Module::Runtime is a good
86 way to check for something you might be able to call methods on if you
87 want to do that.
88
89 We are careful to make sure that scalar/list context is preserved for
90 the method that is eventually called.
91
92EXPORTS
93 $_isa
94 $maybe_an_object->$_isa('Foo');
95
96 If called on an object, calls "isa" on it and returns the result,
97 otherwise returns nothing.
98
99 $_can
100 $maybe_an_object->$_can('Foo');
101
102 If called on an object, calls "can" on it and returns the result,
103 otherwise returns nothing.
104
105 $_does
106 $maybe_an_object->$_does('Foo');
107
108 If called on an object, calls "does" on it and returns the result,
109 otherwise returns nothing. If the "does" method does not exist, returns
110 nothing rather than failing.
111
112 $_DOES
113 $maybe_an_object->$_DOES('Foo');
114
115 If called on an object, calls "DOES" on it and returns the result,
116 otherwise returns nothing. On perl versions prior to 5.10.0, the built
117 in core "DOES" method doesn't exist. If the method doesn't exist, this
118 will fall back to calling "isa" just like the core "DOES" method.
119
120 $_call_if_object
121 $maybe_an_object->$_call_if_object(method_name => @args);
122
123 If called on an object, calls "method_name" on it and returns the
124 result, otherwise returns nothing.
125
126 $_call_if_can
127 $maybe_an_object->$_call_if_can(name => @args);
128
129 If called on an object, calls "can" on it; if that returns true, then
130 calls "method_name" on it and returns the result; if any condition is
131 false returns nothing.
132
133SEE ALSO
134 I gave a lightning talk on this module (and curry and Import::Into) at
135 YAPC::NA 2013 <https://www.youtube.com/watch?v=wFXWV2yY7gE&t=46m05s>.
136
137AUTHOR
138 mst - Matt S. Trout (cpan:MSTROUT) <mst@shadowcat.co.uk>
139
140CONTRIBUTORS
141 None yet. Well volunteered? :)
142
143COPYRIGHT
144 Copyright (c) 2012 the Safe::Isa "AUTHOR" and "CONTRIBUTORS" as listed
145 above.
146
147LICENSE
148 This library is free software and may be distributed under the same
149 terms as perl itself.
150
151