This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Bump up UNIVERSAL's version to 1.02
[perl5.git] / lib / UNIVERSAL.pm
CommitLineData
def3c102
PP
1package UNIVERSAL;
2
c5d4c348 3our $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 11require 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
16sub import {
17 return unless $_[0] eq __PACKAGE__;
18 goto &Exporter::import;
19}
20
def3c102
PP
211;
22__END__
23
24=head1 NAME
25
26UNIVERSAL - 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
PP
41=head1 DESCRIPTION
42
43C<UNIVERSAL> is the base class which all bless references will inherit from,
ea8fae29 44see L<perlobj>.
def3c102 45
ea8fae29 46C<UNIVERSAL> provides the following methods and functions:
def3c102
PP
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
56Where
57
58=over 4
59
60=item C<TYPE>
61
62is a package name
63
64=item C<$obj>
65
66is a blessed reference or a string containing a package name
67
68=item C<CLASS>
69
70is a package name
71
72=item C<VAL>
73
74is any of the above or an unblessed reference
75
76=back
77
78When used as an instance or class method (C<< $obj->isa( TYPE ) >>),
79C<isa> returns I<true> if $obj is blessed into package C<TYPE> or
80inherits from package C<TYPE>.
81
82When used as a class method (C<< CLASS->isa( TYPE ) >>: sometimes
83referred to as a static method), C<isa> returns I<true> if C<CLASS>
84inherits from (or is itself) the name of the package C<TYPE> or
85inherits from package C<TYPE>.
ea8fae29
BS
86
87When used as a function, like
88
89 use UNIVERSAL qw( isa ) ;
90 $yes = isa $h, "HASH";
91 $yes = isa "Foo", "Bar";
def3c102 92
ea8fae29 93or
def3c102 94
ea8fae29
BS
95 require UNIVERSAL ;
96 $yes = UNIVERSAL::isa $a, "ARRAY";
def3c102 97
a2b59c1f 98C<isa> returns I<true> in the same cases as above and also if C<VAL> is an
ea8fae29
BS
99unblessed 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
108C<can> checks if the object or class has a method called C<METHOD>. If it does
109then a reference to the sub is returned. If it does not then I<undef> is
110returned. This includes methods inherited or imported by C<$obj>, C<CLASS>, or
111C<VAL>.
def3c102 112
04b85669
TB
113C<can> cannot know whether an object will be able to provide a method
114through AUTOLOAD, so a return value of I<undef> does not necessarily mean
115the object will not be able to handle the method call. To get around
116this some module authors use a forward declaration (see L<perlsub>)
117for methods they will handle via AUTOLOAD. For such 'dummy' subs, C<can>
118will still return a code reference, which, when called, will fall through
119to the AUTOLOAD. If no suitable AUTOLOAD is provided, calling the coderef
120will cause an error.
121
ea8fae29
BS
122C<can> can be called as a class (static) method, an object method, or a
123function.
124
125When used as a function, if C<VAL> is a blessed reference or package name which
126has a method called C<METHOD>, C<can> returns a reference to the subroutine.
127If C<VAL> is not a blessed reference, or if it does not have a method
128C<METHOD>, I<undef> is returned.
def3c102 129
a2b59c1f 130=item C<VERSION ( [ REQUIRE ] )>
def3c102
PP
131
132C<VERSION> will return the value of the variable C<$VERSION> in the
133package the object is blessed into. If C<REQUIRE> is given then
134it will do a comparison and die if the package version is not
135greater than or equal to C<REQUIRE>.
136
a2b59c1f
CW
137C<VERSION> can be called as either a class (static) method, an object
138method or a function.
a66bc3b0 139
a66bc3b0 140
def3c102
PP
141=back
142
a2b59c1f 143=head1 EXPORTS
84902520 144
a2b59c1f 145None by default.
84902520 146
a2b59c1f
CW
147You may request the import of all three functions (C<isa>, C<can>, and
148C<VERSION>), however it isn't usually necessary to do so. Perl magically
149makes these functions act as methods on all objects. The one exception is
150C<isa>, which is useful as a function when operating on non-blessed
151references.
84902520 152
def3c102 153=cut