Unused return value.
[perl.git] / lib / UNIVERSAL.pm
1 package UNIVERSAL;
2
3 our $VERSION = '1.12';
4
5 # UNIVERSAL should not contain any extra subs/methods beyond those
6 # that it exists to define. The existence of import() below is a historical
7 # accident that can't be fixed without breaking code.
8
9 # Make sure that even though the import method is called, it doesn't do
10 # anything unless called on UNIVERSAL.
11 sub import {
12     return unless $_[0] eq __PACKAGE__;
13     return unless @_ > 1;
14     require Carp;
15     Carp::croak("UNIVERSAL does not export anything");
16 }
17
18 1;
19 __END__
20
21 =head1 NAME
22
23 UNIVERSAL - base class for ALL classes (blessed references)
24
25 =head1 SYNOPSIS
26
27     $is_io    = $fd->isa("IO::Handle");
28     $is_io    = Class->isa("IO::Handle");
29
30     $does_log = $obj->DOES("Logger");
31     $does_log = Class->DOES("Logger");
32
33     $sub      = $obj->can("print");
34     $sub      = Class->can("print");
35
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");
42
43 =head1 DESCRIPTION
44
45 C<UNIVERSAL> is the base class from which all blessed references inherit.
46 See L<perlobj>.
47
48 C<UNIVERSAL> provides the following methods:
49
50 =over 4
51
52 =item C<< $obj->isa( TYPE ) >>
53
54 =item C<< CLASS->isa( TYPE ) >>
55
56 =item C<< eval { VAL->isa( TYPE ) } >>
57
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 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
84 When used as a class method (C<< CLASS->isa( TYPE ) >>, sometimes
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>.
88
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.
91
92 If you want to be sure that you're calling C<isa> as a method, not a class,
93 check the invocand with C<blessed> from L<Scalar::Util> first:
94
95   use Scalar::Util 'blessed';
96
97   if ( blessed( $obj ) && $obj->isa("Some::Class") ) {
98       ...
99   }
100
101 =item C<< $obj->DOES( ROLE ) >>
102
103 =item C<< CLASS->DOES( ROLE ) >>
104
105 C<DOES> checks if the object or class performs the role C<ROLE>.  A role is a
106 named group of specific behavior (often methods of particular names and
107 signatures), similar to a class, but not necessarily a complete class by
108 itself.  For example, logging or serialization may be roles.
109
110 C<DOES> and C<isa> are similar, in that if either is true, you know that the
111 object or class on which you call the method can perform specific behavior.
112 However, C<DOES> is different from C<isa> in that it does not care I<how> the
113 invocand performs the operations, merely that it does.  (C<isa> of course
114 mandates an inheritance relationship.  Other relationships include aggregation,
115 delegation, and mocking.)
116
117 By default, classes in Perl only perform the C<UNIVERSAL> role, as well as the
118 role of all classes in their inheritance.  In other words, by default C<DOES>
119 responds identically to C<isa>.
120
121 There is a relationship between roles and classes, as each class implies the
122 existence of a role of the same name.  There is also a relationship between
123 inheritance and roles, in that a subclass that inherits from an ancestor class
124 implicitly performs any roles its parent performs.  Thus you can use C<DOES> in
125 place of C<isa> safely, as it will return true in all places where C<isa> will
126 return true (provided that any overridden C<DOES> I<and> C<isa> methods behave
127 appropriately).
128
129 =item C<< $obj->can( METHOD ) >>
130
131 =item C<< CLASS->can( METHOD ) >>
132
133 =item C<< eval { VAL->can( METHOD ) } >>
134
135 C<can> checks if the object or class has a method called C<METHOD>. If it does,
136 then it returns a reference to the sub.  If it does not, then it returns
137 I<undef>.  This includes methods inherited or imported by C<$obj>, C<CLASS>, or
138 C<VAL>.
139
140 C<can> cannot know whether an object will be able to provide a method through
141 AUTOLOAD (unless the object's class has overridden C<can> appropriately), so a
142 return value of I<undef> does not necessarily mean the object will not be able
143 to handle the method call. To get around this some module authors use a forward
144 declaration (see L<perlsub>) for methods they will handle via AUTOLOAD. For
145 such 'dummy' subs, C<can> will still return a code reference, which, when
146 called, will fall through to the AUTOLOAD. If no suitable AUTOLOAD is provided,
147 calling the coderef will cause an error.
148
149 You may call C<can> as a class (static) method or an object method.
150
151 Again, the same rule about having a valid invocand applies -- use an C<eval>
152 block or C<blessed> if you need to be extra paranoid.
153
154 =item C<VERSION ( [ REQUIRE ] )>
155
156 C<VERSION> will return the value of the variable C<$VERSION> in the
157 package the object is blessed into. If C<REQUIRE> is given then
158 it will do a comparison and die if the package version is not
159 greater than or equal to C<REQUIRE>, or if either C<$VERSION> or C<REQUIRE>
160 is not a "lax" version number (as defined by the L<version> module).
161
162 The return from C<VERSION> will actually be the stringified version object
163 using the package C<$VERSION> scalar, which is guaranteed to be equivalent
164 but may not be precisely the contents of the C<$VERSION> scalar.  If you want
165 the actual contents of C<$VERSION>, use C<$CLASS::VERSION> instead.
166
167 C<VERSION> can be called as either a class (static) method or an object
168 method.
169
170 =back
171
172 =head1 WARNINGS
173
174 B<NOTE:> C<can> directly uses Perl's internal code for method lookup, and
175 C<isa> uses a very similar method and cache-ing strategy. This may cause
176 strange effects if the Perl code dynamically changes @ISA in any package.
177
178 You may add other methods to the UNIVERSAL class via Perl or XS code.
179 You do not need to C<use UNIVERSAL> to make these methods
180 available to your program (and you should not do so).
181
182 =head1 EXPORTS
183
184 None.
185
186 Previous versions of this documentation suggested using C<isa> as
187 a function to determine the type of a reference:
188
189   use UNIVERSAL 'isa';
190
191   $yes = isa $h, "HASH";
192   $yes = isa "Foo", "Bar";
193
194 The problem is that this code would I<never> call an overridden C<isa> method in
195 any class.  Instead, use C<reftype> from L<Scalar::Util> for the first case:
196
197   use Scalar::Util 'reftype';
198
199   $yes = reftype( $h ) eq "HASH";
200
201 and the method form of C<isa> for the second:
202
203   $yes = Foo->isa("Bar");
204
205 =cut