Commit | Line | Data |
---|---|---|
def3c102 | 1 | package UNIVERSAL; |
2 | ||
71ccbdc2 | 3 | our $VERSION = '1.03'; |
b75c8c73 | 4 | |
84902520 TB |
5 | # UNIVERSAL should not contain any extra subs/methods beyond those |
6 | # that it exists to define. The use of Exporter below is a historical | |
ea8fae29 | 7 | # accident that can't be fixed without breaking code. Note that we |
71ccbdc2 | 8 | # *don't* set @ISA here, as we don't want all classes/objects inheriting from |
ea8fae29 BS |
9 | # Exporter. It's bad enough that all classes have a import() method |
10 | # whenever UNIVERSAL.pm is loaded. | |
def3c102 | 11 | require Exporter; |
ea8fae29 | 12 | @EXPORT_OK = qw(isa can VERSION); |
def3c102 | 13 | |
2bfd5681 | 14 | # Make sure that even though the import method is called, it doesn't do |
71ccbdc2 | 15 | # anything unless called on UNIVERSAL. |
2bfd5681 MS |
16 | sub import { |
17 | return unless $_[0] eq __PACKAGE__; | |
18 | goto &Exporter::import; | |
19 | } | |
20 | ||
def3c102 | 21 | 1; |
22 | __END__ | |
23 | ||
24 | =head1 NAME | |
25 | ||
26 | UNIVERSAL - base class for ALL classes (blessed references) | |
27 | ||
28 | =head1 SYNOPSIS | |
29 | ||
ea8fae29 BS |
30 | $is_io = $fd->isa("IO::Handle"); |
31 | $is_io = Class->isa("IO::Handle"); | |
def3c102 | 32 | |
71ccbdc2 | 33 | $sub = $obj->can("print"); |
34 | $sub = Class->can("print"); | |
ea8fae29 | 35 | |
71ccbdc2 | 36 | $sub = eval { $ref->can("fandango") }; |
37 | $ver = $obj->VERSION; | |
38 | ||
39 | # but never do this! | |
40 | $is_io = UNIVERSAL::isa($fd, "IO::Handle"); | |
41 | $sub = UNIVERSAL::can($obj, "print"); | |
84902520 | 42 | |
def3c102 | 43 | =head1 DESCRIPTION |
44 | ||
71ccbdc2 | 45 | C<UNIVERSAL> is the base class from which all blessed references inherit. |
46 | See L<perlobj>. | |
def3c102 | 47 | |
71ccbdc2 | 48 | C<UNIVERSAL> provides the following methods: |
def3c102 | 49 | |
50 | =over 4 | |
51 | ||
a2b59c1f | 52 | =item C<< $obj->isa( TYPE ) >> |
ea8fae29 | 53 | |
71ccbdc2 | 54 | =item C<< CLASS->isa( TYPE ) >> |
ea8fae29 | 55 | |
71ccbdc2 | 56 | =item C<< eval { VAL->isa( TYPE ) } >> |
ea8fae29 | 57 | |
a2b59c1f CW |
58 | Where |
59 | ||
60 | =over 4 | |
61 | ||
62 | =item C<TYPE> | |
63 | ||
64 | is a package name | |
65 | ||
66 | =item C<$obj> | |
67 | ||
68 | is a blessed reference or a string containing a package name | |
69 | ||
70 | =item C<CLASS> | |
71 | ||
72 | is a package name | |
73 | ||
74 | =item C<VAL> | |
75 | ||
76 | is any of the above or an unblessed reference | |
77 | ||
78 | =back | |
79 | ||
80 | When used as an instance or class method (C<< $obj->isa( TYPE ) >>), | |
81 | C<isa> returns I<true> if $obj is blessed into package C<TYPE> or | |
82 | inherits from package C<TYPE>. | |
83 | ||
71ccbdc2 | 84 | When used as a class method (C<< CLASS->isa( TYPE ) >>, sometimes |
a2b59c1f CW |
85 | referred to as a static method), C<isa> returns I<true> if C<CLASS> |
86 | inherits from (or is itself) the name of the package C<TYPE> or | |
87 | inherits from package C<TYPE>. | |
ea8fae29 | 88 | |
71ccbdc2 | 89 | If you're not sure what you have (the C<VAL> case), wrap the method call in an |
90 | C<eval> block to catch the exception if C<VAL> is undefined. | |
def3c102 | 91 | |
71ccbdc2 | 92 | If you want to be sure that you're calling C<isa> as a method, not a class, |
93 | check the invocant with C<blessed> from L<Scalar::Util> first: | |
def3c102 | 94 | |
71ccbdc2 | 95 | use Scalar::Util 'blessed'; |
def3c102 | 96 | |
71ccbdc2 | 97 | if ( blessed( $obj ) && $obj->isa("Some::Class") { |
98 | ... | |
99 | } | |
def3c102 | 100 | |
a2b59c1f CW |
101 | =item C<< $obj->can( METHOD ) >> |
102 | ||
103 | =item C<< CLASS->can( METHOD ) >> | |
104 | ||
71ccbdc2 | 105 | =item C<< eval { VAL->can( METHOD ) } >> |
ea8fae29 | 106 | |
71ccbdc2 | 107 | C<can> checks if the object or class has a method called C<METHOD>. If it does, |
108 | then it returns a reference to the sub. If it does not, then it returns | |
109 | I<undef>. This includes methods inherited or imported by C<$obj>, C<CLASS>, or | |
ea8fae29 | 110 | C<VAL>. |
def3c102 | 111 | |
71ccbdc2 | 112 | C<can> cannot know whether an object will be able to provide a method through |
113 | AUTOLOAD (unless the object's class has overriden C<can> appropriately), so a | |
114 | return value of I<undef> does not necessarily mean the object will not be able | |
115 | to handle the method call. To get around this some module authors use a forward | |
116 | declaration (see L<perlsub>) for methods they will handle via AUTOLOAD. For | |
117 | such 'dummy' subs, C<can> will still return a code reference, which, when | |
118 | called, will fall through to the AUTOLOAD. If no suitable AUTOLOAD is provided, | |
119 | calling the coderef will cause an error. | |
04b85669 | 120 | |
71ccbdc2 | 121 | You may call C<can> as a class (static) method or an object method. |
ea8fae29 | 122 | |
71ccbdc2 | 123 | Again, the same rule about having a valid invocant applies -- use an C<eval> |
124 | block or C<blessed> if you need to be extra paranoid. | |
def3c102 | 125 | |
a2b59c1f | 126 | =item C<VERSION ( [ REQUIRE ] )> |
def3c102 | 127 | |
128 | C<VERSION> will return the value of the variable C<$VERSION> in the | |
129 | package the object is blessed into. If C<REQUIRE> is given then | |
130 | it will do a comparison and die if the package version is not | |
131 | greater than or equal to C<REQUIRE>. | |
132 | ||
71ccbdc2 | 133 | C<VERSION> can be called as either a class (static) method or an object |
134 | method. | |
a66bc3b0 | 135 | |
def3c102 | 136 | =back |
137 | ||
a2b59c1f | 138 | =head1 EXPORTS |
84902520 | 139 | |
a2b59c1f | 140 | None by default. |
84902520 | 141 | |
a2b59c1f | 142 | You may request the import of all three functions (C<isa>, C<can>, and |
71ccbdc2 | 143 | C<VERSION>), however it is usually harmful to do so. Please don't do this in |
144 | new code. | |
145 | ||
146 | For example, previous versions of this documentation suggested using C<isa> as | |
147 | a function to determine the type of a reference: | |
148 | ||
149 | use UNIVERSAL 'isa'; | |
150 | ||
151 | $yes = isa $h, "HASH"; | |
152 | $yes = isa "Foo", "Bar"; | |
153 | ||
154 | The problem is that this code will I<never> call an overridden C<isa> method in | |
155 | any class. Instead, use C<reftype> from L<Scalar::Util> for the first case: | |
156 | ||
157 | use Scalar::Util 'reftype'; | |
158 | ||
159 | $yes = reftype( $h ) eq "HASH"; | |
160 | ||
161 | and the method form of C<isa> for the second: | |
162 | ||
163 | $yes = Foo->isa("Bar"); | |
84902520 | 164 | |
def3c102 | 165 | =cut |