Commit | Line | Data |
---|---|---|
def3c102 | 1 | package UNIVERSAL; |
2 | ||
c5d4c348 | 3 | our $VERSION = '1.02'; |
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 BS |
7 | # accident that can't be fixed without breaking code. Note that we |
8 | # *don't* set @ISA here, don't want all classes/objects inheriting from | |
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 MS |
14 | # Make sure that even though the import method is called, it doesn't do |
15 | # anything unless its called on UNIVERSAL | |
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 | |
ea8fae29 BS |
33 | $sub = $obj->can("print"); |
34 | $sub = Class->can("print"); | |
35 | ||
36 | use UNIVERSAL qw( isa can VERSION ); | |
37 | $yes = isa $ref, "HASH" ; | |
38 | $sub = can $ref, "fandango" ; | |
39 | $ver = VERSION $obj ; | |
84902520 | 40 | |
def3c102 | 41 | =head1 DESCRIPTION |
42 | ||
43 | C<UNIVERSAL> is the base class which all bless references will inherit from, | |
ea8fae29 | 44 | see L<perlobj>. |
def3c102 | 45 | |
ea8fae29 | 46 | C<UNIVERSAL> provides the following methods and functions: |
def3c102 | 47 | |
48 | =over 4 | |
49 | ||
a2b59c1f | 50 | =item C<< $obj->isa( TYPE ) >> |
ea8fae29 | 51 | |
a2b59c1f | 52 | =item C<< CLASS->isa( TYPE ) >> |
ea8fae29 | 53 | |
a2b59c1f | 54 | =item C<isa( VAL, TYPE )> |
ea8fae29 | 55 | |
a2b59c1f CW |
56 | Where |
57 | ||
58 | =over 4 | |
59 | ||
60 | =item C<TYPE> | |
61 | ||
62 | is a package name | |
63 | ||
64 | =item C<$obj> | |
65 | ||
66 | is a blessed reference or a string containing a package name | |
67 | ||
68 | =item C<CLASS> | |
69 | ||
70 | is a package name | |
71 | ||
72 | =item C<VAL> | |
73 | ||
74 | is any of the above or an unblessed reference | |
75 | ||
76 | =back | |
77 | ||
78 | When used as an instance or class method (C<< $obj->isa( TYPE ) >>), | |
79 | C<isa> returns I<true> if $obj is blessed into package C<TYPE> or | |
80 | inherits from package C<TYPE>. | |
81 | ||
82 | When used as a class method (C<< CLASS->isa( TYPE ) >>: sometimes | |
83 | referred to as a static method), C<isa> returns I<true> if C<CLASS> | |
84 | inherits from (or is itself) the name of the package C<TYPE> or | |
85 | inherits from package C<TYPE>. | |
ea8fae29 BS |
86 | |
87 | When used as a function, like | |
88 | ||
89 | use UNIVERSAL qw( isa ) ; | |
90 | $yes = isa $h, "HASH"; | |
91 | $yes = isa "Foo", "Bar"; | |
def3c102 | 92 | |
ea8fae29 | 93 | or |
def3c102 | 94 | |
ea8fae29 BS |
95 | require UNIVERSAL ; |
96 | $yes = UNIVERSAL::isa $a, "ARRAY"; | |
def3c102 | 97 | |
a2b59c1f | 98 | C<isa> returns I<true> in the same cases as above and also if C<VAL> is an |
ea8fae29 BS |
99 | unblessed reference to a perl variable of type C<TYPE>, such as "HASH", |
100 | "ARRAY", or "Regexp". | |
def3c102 | 101 | |
a2b59c1f CW |
102 | =item C<< $obj->can( METHOD ) >> |
103 | ||
104 | =item C<< CLASS->can( METHOD ) >> | |
105 | ||
106 | =item C<can( VAL, METHOD )> | |
ea8fae29 BS |
107 | |
108 | C<can> checks if the object or class has a method called C<METHOD>. If it does | |
109 | then a reference to the sub is returned. If it does not then I<undef> is | |
110 | returned. This includes methods inherited or imported by C<$obj>, C<CLASS>, or | |
111 | C<VAL>. | |
def3c102 | 112 | |
04b85669 TB |
113 | C<can> cannot know whether an object will be able to provide a method |
114 | through AUTOLOAD, so a return value of I<undef> does not necessarily mean | |
115 | the object will not be able to handle the method call. To get around | |
116 | this some module authors use a forward declaration (see L<perlsub>) | |
117 | for methods they will handle via AUTOLOAD. For such 'dummy' subs, C<can> | |
118 | will still return a code reference, which, when called, will fall through | |
119 | to the AUTOLOAD. If no suitable AUTOLOAD is provided, calling the coderef | |
120 | will cause an error. | |
121 | ||
ea8fae29 BS |
122 | C<can> can be called as a class (static) method, an object method, or a |
123 | function. | |
124 | ||
125 | When used as a function, if C<VAL> is a blessed reference or package name which | |
126 | has a method called C<METHOD>, C<can> returns a reference to the subroutine. | |
127 | If C<VAL> is not a blessed reference, or if it does not have a method | |
128 | C<METHOD>, I<undef> is returned. | |
def3c102 | 129 | |
a2b59c1f | 130 | =item C<VERSION ( [ REQUIRE ] )> |
def3c102 | 131 | |
132 | C<VERSION> will return the value of the variable C<$VERSION> in the | |
133 | package the object is blessed into. If C<REQUIRE> is given then | |
134 | it will do a comparison and die if the package version is not | |
135 | greater than or equal to C<REQUIRE>. | |
136 | ||
a2b59c1f CW |
137 | C<VERSION> can be called as either a class (static) method, an object |
138 | method or a function. | |
a66bc3b0 | 139 | |
a66bc3b0 | 140 | |
def3c102 | 141 | =back |
142 | ||
a2b59c1f | 143 | =head1 EXPORTS |
84902520 | 144 | |
a2b59c1f | 145 | None by default. |
84902520 | 146 | |
a2b59c1f CW |
147 | You may request the import of all three functions (C<isa>, C<can>, and |
148 | C<VERSION>), however it isn't usually necessary to do so. Perl magically | |
149 | makes these functions act as methods on all objects. The one exception is | |
150 | C<isa>, which is useful as a function when operating on non-blessed | |
151 | references. | |
84902520 | 152 | |
def3c102 | 153 | =cut |