This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Re: [PATCH] Added wisdom to perlhack.pod
[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
48C<can> can be called as either a static or object method call.
49
50=item VERSION ( [ REQUIRE ] )
51
52C<VERSION> will return the value of the variable C<$VERSION> in the
53package the object is blessed into. If C<REQUIRE> is given then
54it will do a comparison and die if the package version is not
55greater than or equal to C<REQUIRE>.
56
57C<VERSION> can be called as either a static or object method call.
58
59=back
60
84902520 61The C<isa> and C<can> methods can also be called as subroutines
def3c102
PP
62
63=over 4
64
84902520 65=item UNIVERSAL::isa ( VAL, TYPE )
def3c102 66
96f1132b 67C<isa> returns I<true> if one of the following statements is true.
def3c102
PP
68
69=over 8
70
a45bd81d 71=item *
def3c102 72
96f1132b
GS
73C<VAL> is a reference blessed into either package C<TYPE> or a package
74which inherits from package C<TYPE>.
def3c102 75
a45bd81d 76=item *
def3c102 77
96f1132b
GS
78C<VAL> is a reference to a C<TYPE> of Perl variable (e.g. 'HASH').
79
80=item *
81
82C<VAL> is the name of a package that inherits from (or is itself)
83package C<TYPE>.
def3c102
PP
84
85=back
86
84902520 87=item UNIVERSAL::can ( VAL, METHOD )
a66bc3b0
G
88
89If C<VAL> is a blessed reference which has a method called C<METHOD>,
90C<can> returns a reference to the subroutine. If C<VAL> is not
91a blessed reference, or if it does not have a method C<METHOD>,
92I<undef> is returned.
93
def3c102
PP
94=back
95
84902520
TB
96These subroutines should I<not> be imported via S<C<use UNIVERSAL qw(...)>>.
97If you want simple local access to them you can do
98
99 *isa = \&UNIVERSAL::isa;
100
101to import isa into your package.
102
def3c102 103=cut