Safe::Isa(3pm)

1Safe::Isa(3)          User Contributed Perl Documentation         Safe::Isa(3)
2
3
4

NAME

6       Safe::Isa - Call isa, can, does and DOES safely on things that may not
7       be objects
8

SYNOPSIS

10         use strict;
11         use warnings;
12
13         { package Foo; sub new { bless({}, $_[0]) } }
14         { package Bar; our @ISA = qw(Foo); sub bar { 1 } }
15
16         my $foo = Foo->new;
17         my $bar = Bar->new;
18         my $blam = [ 42 ];
19
20         # basic isa usage -
21
22         $foo->isa('Foo');  # true
23         $bar->isa('Foo');  # true
24         $blam->isa('Foo'); # BOOM
25
26         $foo->can('bar');  # false
27         $bar->can('bar');  # true
28         $blam->can('bar'); # BOOM
29
30         # Safe::Isa usage -
31
32         use Safe::Isa;
33
34         $foo->$_isa('Foo');  # true
35         $bar->$_isa('Foo');  # true
36         $blam->$_isa('Foo'); # false, no boom today
37
38         $foo->$_can('bar');  # false
39         $bar->$_can('bar');  # true
40         $blam->$_can('bar'); # false, no boom today
41
42       Similarly:
43
44         $maybe_an_object->$_does('RoleName'); # true or false, no boom today
45         $maybe_an_object->$_DOES('RoleName'); # true or false, no boom today
46
47       And just in case we missed a method or two:
48
49         $maybe_an_object->$_call_if_object(name => @args);
50         $maybe_an_object->$_call_if_can(name => @args);
51
52       Or to re-use a previous example for purposes of explication:
53
54         $foo->$_call_if_object(isa => 'Foo');  # true
55         $bar->$_call_if_object(isa => 'Foo');  # true
56         $blam->$_call_if_object(isa => 'Foo'); # false, no boom today
57

DESCRIPTION

59       How many times have you found yourself writing:
60
61         if ($obj->isa('Something')) {
62
63       and then shortly afterwards cursing and changing it to:
64
65         if (Scalar::Util::blessed($obj) and $obj->isa('Something')) {
66
67       Right. That's why this module exists.
68
69       Since perl allows us to provide a subroutine reference or a method name
70       to the -> operator when used as a method call, and a subroutine doesn't
71       require the invocant to actually be an object, we can create safe
72       versions of isa, can and friends by using a subroutine reference that
73       only tries to call the method if it's used on an object. So:
74
75         my $isa_Foo = $maybe_an_object->$_call_if_object(isa => 'Foo');
76
77       is equivalent to
78
79         my $isa_Foo = do {
80           if (Scalar::Util::blessed($maybe_an_object)) {
81             $maybe_an_object->isa('Foo');
82           } else {
83             undef;
84           }
85         };
86
87       Note that we don't handle trying class names, because many things are
88       valid class names that you might not want to treat as one (like say
89       "Matt") - the "is_module_name" function from Module::Runtime is a good
90       way to check for something you might be able to call methods on if you
91       want to do that.
92
93       We are careful to make sure that scalar/list context is preserved for
94       the method that is eventually called.
95

EXPORTS

97   $_isa
98         $maybe_an_object->$_isa('Foo');
99
100       If called on an object, calls "isa" on it and returns the result,
101       otherwise returns nothing.
102
103   $_can
104         $maybe_an_object->$_can('Foo');
105
106       If called on an object, calls "can" on it and returns the result,
107       otherwise returns nothing.
108
109   $_does
110         $maybe_an_object->$_does('Foo');
111
112       If called on an object, calls "does" on it and returns the result,
113       otherwise returns nothing. If the "does" method does not exist, returns
114       nothing rather than failing.
115
116   $_DOES
117         $maybe_an_object->$_DOES('Foo');
118
119       If called on an object, calls "DOES" on it and returns the result,
120       otherwise returns nothing. On perl versions prior to 5.10.0, the built
121       in core "DOES" method doesn't exist. If the method doesn't exist, this
122       will fall back to calling "isa" just like the core "DOES" method.
123
124   $_call_if_object
125         $maybe_an_object->$_call_if_object(method_name => @args);
126
127       If called on an object, calls "method_name" on it and returns the
128       result, otherwise returns nothing.
129
130   $_call_if_can
131         $maybe_an_object->$_call_if_can(name => @args);
132
133       If called on an object, calls "can" on it; if that returns true, then
134       calls "method_name" on it and returns the result; if any condition is
135       false returns nothing.
136

AUTHOR

142       mst - Matt S. Trout (cpan:MSTROUT) <mst@shadowcat.co.uk>
143

CONTRIBUTORS

145       None yet. Well volunteered? :)
146

COPYRIGHT

148       Copyright (c) 2012 the Safe::Isa "AUTHOR" and "CONTRIBUTORS" as listed
149       above.
150

LICENSE

152       This library is free software and may be distributed under the same
153       terms as perl itself.
154
155
156
157perl v5.34.0                      2022-01-21                      Safe::Isa(3)