Profile of /usr/local/lib/perl5/5.8.8/UNIVERSAL.pm

File	/usr/local/lib/perl5/5.8.8/UNIVERSAL.pm
Statements Executed	5
Statement Execution Time	44µs

Call graph for these subroutines as a Graphviz dot language file.

Line	State ments	Time on line	Code
1			package UNIVERSAL;
2
3	1	5µs	our $VERSION = '1.01';
4
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 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.
11	1	6µs	require Exporter;
12	1	9µs	*import = \&Exporter::import;
13	1	7µs	@EXPORT_OK = qw(isa can VERSION);
14
15	1	17µs	1;
16			__END__
17
18			=head1 NAME
19
20			UNIVERSAL - base class for ALL classes (blessed references)
21
22			=head1 SYNOPSIS
23
24			$is_io = $fd->isa("IO::Handle");
25			$is_io = Class->isa("IO::Handle");
26
27			$sub = $obj->can("print");
28			$sub = Class->can("print");
29
30			use UNIVERSAL qw( isa can VERSION );
31			$yes = isa $ref, "HASH" ;
32			$sub = can $ref, "fandango" ;
33			$ver = VERSION $obj ;
34
35			=head1 DESCRIPTION
36
37			C<UNIVERSAL> is the base class which all bless references will inherit from,
38			see L<perlobj>.
39
40			C<UNIVERSAL> provides the following methods and functions:
41
42			=over 4
43
44			=item C<< $obj->isa( TYPE ) >>
45
46			=item C<< CLASS->isa( TYPE ) >>
47
48			=item C<isa( VAL, TYPE )>
49
50			Where
51
52			=over 4
53
54			=item C<TYPE>
55
56			is a package name
57
58			=item C<$obj>
59
60			is a blessed reference or a string containing a package name
61
62			=item C<CLASS>
63
64			is a package name
65
66			=item C<VAL>
67
68			is any of the above or an unblessed reference
69
70			=back
71
72			When used as an instance or class method (C<< $obj->isa( TYPE ) >>),
73			C<isa> returns I<true> if $obj is blessed into package C<TYPE> or
74			inherits from package C<TYPE>.
75
76			When used as a class method (C<< CLASS->isa( TYPE ) >>: sometimes
77			referred to as a static method), C<isa> returns I<true> if C<CLASS>
78			inherits from (or is itself) the name of the package C<TYPE> or
79			inherits from package C<TYPE>.
80
81			When used as a function, like
82
83			use UNIVERSAL qw( isa ) ;
84			$yes = isa $h, "HASH";
85			$yes = isa "Foo", "Bar";
86
87			or
88
89			require UNIVERSAL ;
90			$yes = UNIVERSAL::isa $a, "ARRAY";
91
92			C<isa> returns I<true> in the same cases as above and also if C<VAL> is an
93			unblessed reference to a perl variable of type C<TYPE>, such as "HASH",
94			"ARRAY", or "Regexp".
95
96			=item C<< $obj->can( METHOD ) >>
97
98			=item C<< CLASS->can( METHOD ) >>
99
100			=item C<can( VAL, METHOD )>
101
102			C<can> checks if the object or class has a method called C<METHOD>. If it does
103			then a reference to the sub is returned. If it does not then I<undef> is
104			returned. This includes methods inherited or imported by C<$obj>, C<CLASS>, or
105			C<VAL>.
106
107			C<can> cannot know whether an object will be able to provide a method
108			through AUTOLOAD, so a return value of I<undef> does not necessarily mean
109			the object will not be able to handle the method call. To get around
110			this some module authors use a forward declaration (see L<perlsub>)
111			for methods they will handle via AUTOLOAD. For such 'dummy' subs, C<can>
112			will still return a code reference, which, when called, will fall through
113			to the AUTOLOAD. If no suitable AUTOLOAD is provided, calling the coderef
114			will cause an error.
115
116			C<can> can be called as a class (static) method, an object method, or a
117			function.
118
119			When used as a function, if C<VAL> is a blessed reference or package name which
120			has a method called C<METHOD>, C<can> returns a reference to the subroutine.
121			If C<VAL> is not a blessed reference, or if it does not have a method
122			C<METHOD>, I<undef> is returned.
123
124			=item C<VERSION ( [ REQUIRE ] )>
125
126			C<VERSION> will return the value of the variable C<$VERSION> in the
127			package the object is blessed into. If C<REQUIRE> is given then
128			it will do a comparison and die if the package version is not
129			greater than or equal to C<REQUIRE>.
130
131			C<VERSION> can be called as either a class (static) method, an object
132			method or a function.
133
134
135			=back
136
137			=head1 EXPORTS
138
139			None by default.
140
141			You may request the import of all three functions (C<isa>, C<can>, and
142			C<VERSION>), however it isn't usually necessary to do so. Perl magically
143			makes these functions act as methods on all objects. The one exception is
144			C<isa>, which is useful as a function when operating on non-blessed
145			references.
146
147			=cut