This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
docco tweaks
[perl5.git] / lib / UNIVERSAL.pm
CommitLineData
def3c102
PP
1package UNIVERSAL;
2
b75c8c73
MS
3our $VERSION = '1.00';
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
7# accident that should be fixed sometime.
def3c102 8require Exporter;
84902520 9*import = \&Exporter::import;
a66bc3b0 10@EXPORT_OK = qw(isa can);
def3c102
PP
11
121;
13__END__
14
15=head1 NAME
16
17UNIVERSAL - base class for ALL classes (blessed references)
18
19=head1 SYNOPSIS
20
def3c102
PP
21 $io = $fd->isa("IO::Handle");
22 $sub = $obj->can('print');
23
84902520
TB
24 $yes = UNIVERSAL::isa($ref, "HASH");
25
def3c102
PP
26=head1 DESCRIPTION
27
28C<UNIVERSAL> is the base class which all bless references will inherit from,
29see L<perlobj>
30
31C<UNIVERSAL> provides the following methods
32
33=over 4
34
35=item isa ( TYPE )
36
37C<isa> returns I<true> if C<REF> is blessed into package C<TYPE>
38or inherits from package C<TYPE>.
39
40C<isa> can be called as either a static or object method call.
41
42=item can ( METHOD )
43
44C<can> checks if the object has a method called C<METHOD>. If it does
7e1af8bc 45then a reference to the sub is returned. If it does not then I<undef>
def3c102
PP
46is returned.
47
04b85669
TB
48C<can> cannot know whether an object will be able to provide a method
49through AUTOLOAD, so a return value of I<undef> does not necessarily mean
50the object will not be able to handle the method call. To get around
51this some module authors use a forward declaration (see L<perlsub>)
52for methods they will handle via AUTOLOAD. For such 'dummy' subs, C<can>
53will still return a code reference, which, when called, will fall through
54to the AUTOLOAD. If no suitable AUTOLOAD is provided, calling the coderef
55will cause an error.
56
def3c102
PP
57C<can> can be called as either a static or object method call.
58
59=item VERSION ( [ REQUIRE ] )
60
61C<VERSION> will return the value of the variable C<$VERSION> in the
62package the object is blessed into. If C<REQUIRE> is given then
63it will do a comparison and die if the package version is not
64greater than or equal to C<REQUIRE>.
65
66C<VERSION> can be called as either a static or object method call.
67
68=back
69
84902520 70The C<isa> and C<can> methods can also be called as subroutines
def3c102
PP
71
72=over 4
73
84902520 74=item UNIVERSAL::isa ( VAL, TYPE )
def3c102 75
96f1132b 76C<isa> returns I<true> if one of the following statements is true.
def3c102
PP
77
78=over 8
79
a45bd81d 80=item *
def3c102 81
96f1132b
GS
82C<VAL> is a reference blessed into either package C<TYPE> or a package
83which inherits from package C<TYPE>.
def3c102 84
a45bd81d 85=item *
def3c102 86
96f1132b
GS
87C<VAL> is a reference to a C<TYPE> of Perl variable (e.g. 'HASH').
88
89=item *
90
91C<VAL> is the name of a package that inherits from (or is itself)
92package C<TYPE>.
def3c102
PP
93
94=back
95
84902520 96=item UNIVERSAL::can ( VAL, METHOD )
a66bc3b0
G
97
98If C<VAL> is a blessed reference which has a method called C<METHOD>,
99C<can> returns a reference to the subroutine. If C<VAL> is not
100a blessed reference, or if it does not have a method C<METHOD>,
101I<undef> is returned.
102
def3c102
PP
103=back
104
84902520
TB
105These subroutines should I<not> be imported via S<C<use UNIVERSAL qw(...)>>.
106If you want simple local access to them you can do
107
108 *isa = \&UNIVERSAL::isa;
109
110to import isa into your package.
111
def3c102 112=cut