Commit | Line | Data |
---|---|---|
def3c102 | 1 | package UNIVERSAL; |
2 | ||
7d1bbbe8 | 3 | our $VERSION = '1.04'; |
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 | ||
7d1bbbe8 | 30 | $is_io = $fd->isa("IO::Handle"); |
31 | $is_io = Class->isa("IO::Handle"); | |
def3c102 | 32 | |
7d1bbbe8 | 33 | $does_log = $obj->DOES("Logger"); |
34 | $does_log = Class->DOES("Logger"); | |
ea8fae29 | 35 | |
7d1bbbe8 | 36 | $sub = $obj->can("print"); |
37 | $sub = Class->can("print"); | |
38 | ||
39 | $sub = eval { $ref->can("fandango") }; | |
40 | $ver = $obj->VERSION; | |
71ccbdc2 | 41 | |
42 | # but never do this! | |
7d1bbbe8 | 43 | $is_io = UNIVERSAL::isa($fd, "IO::Handle"); |
44 | $sub = UNIVERSAL::can($obj, "print"); | |
84902520 | 45 | |
def3c102 | 46 | =head1 DESCRIPTION |
47 | ||
71ccbdc2 | 48 | C<UNIVERSAL> is the base class from which all blessed references inherit. |
49 | See L<perlobj>. | |
def3c102 | 50 | |
71ccbdc2 | 51 | C<UNIVERSAL> provides the following methods: |
def3c102 | 52 | |
53 | =over 4 | |
54 | ||
a2b59c1f | 55 | =item C<< $obj->isa( TYPE ) >> |
ea8fae29 | 56 | |
71ccbdc2 | 57 | =item C<< CLASS->isa( TYPE ) >> |
ea8fae29 | 58 | |
71ccbdc2 | 59 | =item C<< eval { VAL->isa( TYPE ) } >> |
ea8fae29 | 60 | |
a2b59c1f CW |
61 | Where |
62 | ||
63 | =over 4 | |
64 | ||
65 | =item C<TYPE> | |
66 | ||
67 | is a package name | |
68 | ||
69 | =item C<$obj> | |
70 | ||
71 | is a blessed reference or a string containing a package name | |
72 | ||
73 | =item C<CLASS> | |
74 | ||
75 | is a package name | |
76 | ||
77 | =item C<VAL> | |
78 | ||
79 | is any of the above or an unblessed reference | |
80 | ||
81 | =back | |
82 | ||
83 | When used as an instance or class method (C<< $obj->isa( TYPE ) >>), | |
84 | C<isa> returns I<true> if $obj is blessed into package C<TYPE> or | |
85 | inherits from package C<TYPE>. | |
86 | ||
71ccbdc2 | 87 | When used as a class method (C<< CLASS->isa( TYPE ) >>, sometimes |
a2b59c1f CW |
88 | referred to as a static method), C<isa> returns I<true> if C<CLASS> |
89 | inherits from (or is itself) the name of the package C<TYPE> or | |
90 | inherits from package C<TYPE>. | |
ea8fae29 | 91 | |
71ccbdc2 | 92 | If you're not sure what you have (the C<VAL> case), wrap the method call in an |
93 | C<eval> block to catch the exception if C<VAL> is undefined. | |
def3c102 | 94 | |
71ccbdc2 | 95 | If you want to be sure that you're calling C<isa> as a method, not a class, |
96 | check the invocant with C<blessed> from L<Scalar::Util> first: | |
def3c102 | 97 | |
71ccbdc2 | 98 | use Scalar::Util 'blessed'; |
def3c102 | 99 | |
71ccbdc2 | 100 | if ( blessed( $obj ) && $obj->isa("Some::Class") { |
101 | ... | |
102 | } | |
def3c102 | 103 | |
7d1bbbe8 | 104 | =item C<< $obj->DOES( ROLE ) >> |
105 | ||
106 | =item C<< CLASS->DOES( ROLE ) >> | |
107 | ||
108 | C<DOES> checks if the object or class performs the role C<ROLE>. A role is a | |
109 | named group of specific behavior (often methods of particular names and | |
110 | signatures), similar to a class, but not necessarily a complete class by | |
111 | itself. For example, logging or serialization may be roles. | |
112 | ||
113 | C<DOES> and C<isa> are similar, in that if either is true, you know that the | |
114 | object or class on which you call the method can perform specific behavior. | |
115 | However, C<DOES> is different from C<isa> in that it does not care I<how> the | |
116 | invocant performs the operations, merely that it does. (C<isa> of course | |
117 | mandates an inheritance relationship. Other relationships include aggregation, | |
118 | delegation, and mocking.) | |
119 | ||
bcb8f0e8 RS |
120 | By default, classes in Perl only perform the C<UNIVERSAL> role, as well as the |
121 | role of all classes in their inheritance. In other words, by default C<DOES> | |
122 | responds identically to C<isa>. | |
7d1bbbe8 | 123 | |
124 | There is a relationship between roles and classes, as each class implies the | |
125 | existence of a role of the same name. There is also a relationship between | |
126 | inheritance and roles, in that a subclass that inherits from an ancestor class | |
127 | implicitly performs any roles its parent performs. Thus you can use C<DOES> in | |
128 | place of C<isa> safely, as it will return true in all places where C<isa> will | |
129 | return true (provided that any overridden C<DOES> I<and> C<isa> methods behave | |
130 | appropriately). | |
131 | ||
a2b59c1f CW |
132 | =item C<< $obj->can( METHOD ) >> |
133 | ||
134 | =item C<< CLASS->can( METHOD ) >> | |
135 | ||
71ccbdc2 | 136 | =item C<< eval { VAL->can( METHOD ) } >> |
ea8fae29 | 137 | |
71ccbdc2 | 138 | C<can> checks if the object or class has a method called C<METHOD>. If it does, |
139 | then it returns a reference to the sub. If it does not, then it returns | |
140 | I<undef>. This includes methods inherited or imported by C<$obj>, C<CLASS>, or | |
ea8fae29 | 141 | C<VAL>. |
def3c102 | 142 | |
71ccbdc2 | 143 | C<can> cannot know whether an object will be able to provide a method through |
144 | AUTOLOAD (unless the object's class has overriden C<can> appropriately), so a | |
145 | return value of I<undef> does not necessarily mean the object will not be able | |
146 | to handle the method call. To get around this some module authors use a forward | |
147 | declaration (see L<perlsub>) for methods they will handle via AUTOLOAD. For | |
148 | such 'dummy' subs, C<can> will still return a code reference, which, when | |
149 | called, will fall through to the AUTOLOAD. If no suitable AUTOLOAD is provided, | |
150 | calling the coderef will cause an error. | |
04b85669 | 151 | |
71ccbdc2 | 152 | You may call C<can> as a class (static) method or an object method. |
ea8fae29 | 153 | |
71ccbdc2 | 154 | Again, the same rule about having a valid invocant applies -- use an C<eval> |
155 | block or C<blessed> if you need to be extra paranoid. | |
def3c102 | 156 | |
a2b59c1f | 157 | =item C<VERSION ( [ REQUIRE ] )> |
def3c102 | 158 | |
159 | C<VERSION> will return the value of the variable C<$VERSION> in the | |
160 | package the object is blessed into. If C<REQUIRE> is given then | |
161 | it will do a comparison and die if the package version is not | |
162 | greater than or equal to C<REQUIRE>. | |
163 | ||
71ccbdc2 | 164 | C<VERSION> can be called as either a class (static) method or an object |
165 | method. | |
a66bc3b0 | 166 | |
def3c102 | 167 | =back |
168 | ||
a2b59c1f | 169 | =head1 EXPORTS |
84902520 | 170 | |
a2b59c1f | 171 | None by default. |
84902520 | 172 | |
7d1bbbe8 | 173 | You may request the import of three functions (C<isa>, C<can>, and C<VERSION>), |
174 | however it is usually harmful to do so. Please don't do this in new code. | |
71ccbdc2 | 175 | |
176 | For example, previous versions of this documentation suggested using C<isa> as | |
177 | a function to determine the type of a reference: | |
178 | ||
179 | use UNIVERSAL 'isa'; | |
180 | ||
181 | $yes = isa $h, "HASH"; | |
182 | $yes = isa "Foo", "Bar"; | |
183 | ||
184 | The problem is that this code will I<never> call an overridden C<isa> method in | |
185 | any class. Instead, use C<reftype> from L<Scalar::Util> for the first case: | |
186 | ||
187 | use Scalar::Util 'reftype'; | |
188 | ||
189 | $yes = reftype( $h ) eq "HASH"; | |
190 | ||
191 | and the method form of C<isa> for the second: | |
192 | ||
193 | $yes = Foo->isa("Bar"); | |
84902520 | 194 | |
def3c102 | 195 | =cut |