Debian Codegraph @

upstream/opensuse-tumbleweed/man3/UNIVERSAL.3pm

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\"
56 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "UNIVERSAL 3pm"
61 .TH UNIVERSAL 3pm 2026-03-09 "perl v5.42.1" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 UNIVERSAL \- base class for ALL classes (blessed references)
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 2
71 \& my $obj_is_io = $fd\->isa("IO::Handle");
72 \& my $cls_is_io = Class\->isa("IO::Handle");
73 \&
74 \& my $obj_does_log = $obj\->DOES("Logger");
75 \& my $cls_does_log = Class\->DOES("Logger");
76 \&
77 \& my $obj_sub = $obj\->can("print");
78 \& my $cls_sub = Class\->can("print");
79 \&
80 \& my $eval_sub = eval { $ref\->can("fandango") };
81 \& my $ver = $obj\->VERSION;
82 \&
83 \& # but never do this!
84 \& my $is_io = UNIVERSAL::isa($fd, "IO::Handle");
85 \& my $sub = UNIVERSAL::can($obj, "print");
86 .Ve
87 .SH DESCRIPTION
88 .IX Header "DESCRIPTION"
89 \&\f(CW\*(C`UNIVERSAL\*(C'\fR is the base class from which all blessed references inherit.
90 See perlobj.
91 .PP
92 \&\f(CW\*(C`UNIVERSAL\*(C'\fR provides the following methods:
93 .ie n .IP """$obj\->isa( TYPE )""" 4
94 .el .IP "\f(CW$obj\->isa( TYPE )\fR" 4
95 .IX Item "$obj->isa( TYPE )"
96 .PD 0
97 .ie n .IP """CLASS\->isa( TYPE )""" 4
98 .el .IP "\f(CWCLASS\->isa( TYPE )\fR" 4
99 .IX Item "CLASS->isa( TYPE )"
100 .ie n .IP """eval { VAL\->isa( TYPE ) }""" 4
101 .el .IP "\f(CWeval { VAL\->isa( TYPE ) }\fR" 4
102 .IX Item "eval { VAL->isa( TYPE ) }"
103 .PD
104 Where
105 .RS 4
106 .ie n .IP """TYPE""" 4
107 .el .IP \f(CWTYPE\fR 4
108 .IX Item "TYPE"
109 is a package name
110 .ie n .IP $obj 4
111 .el .IP \f(CW$obj\fR 4
112 .IX Item "$obj"
113 is a blessed reference or a package name
114 .ie n .IP """CLASS""" 4
115 .el .IP \f(CWCLASS\fR 4
116 .IX Item "CLASS"
117 is a package name
118 .ie n .IP """VAL""" 4
119 .el .IP \f(CWVAL\fR 4
120 .IX Item "VAL"
121 is any of the above or an unblessed reference
122 .RE
123 .RS 4
124 .Sp
125 When used as an instance or class method (\f(CW\*(C`$obj\->isa( TYPE )\*(C'\fR),
126 \&\f(CW\*(C`isa\*(C'\fR returns \fItrue\fR if \f(CW$obj\fR is blessed into package \f(CW\*(C`TYPE\*(C'\fR or
127 inherits from package \f(CW\*(C`TYPE\*(C'\fR.
128 .Sp
129 When used as a class method (\f(CW\*(C`CLASS\->isa( TYPE )\*(C'\fR, sometimes
130 referred to as a static method), \f(CW\*(C`isa\*(C'\fR returns \fItrue\fR if \f(CW\*(C`CLASS\*(C'\fR
131 inherits from (or is itself) the name of the package \f(CW\*(C`TYPE\*(C'\fR or
132 inherits from package \f(CW\*(C`TYPE\*(C'\fR.
133 .Sp
134 If you\*(Aqre not sure what you have (the \f(CW\*(C`VAL\*(C'\fR case), wrap the method call in an
135 \&\f(CW\*(C`eval\*(C'\fR block to catch the exception if \f(CW\*(C`VAL\*(C'\fR is undefined or an unblessed
136 reference. The \f(CW\*(C`isa\*(C'\fR operator is an
137 alternative that simply returns false in this case, so the \f(CW\*(C`eval\*(C'\fR is not
138 needed.
139 .Sp
140 If you want to be sure that you\*(Aqre calling \f(CW\*(C`isa\*(C'\fR on an instance, not a class,
141 check the invocant with \f(CW\*(C`blessed\*(C'\fR from Scalar::Util first:
142 .Sp
143 .Vb 1
144 \& use Scalar::Util \*(Aqblessed\*(Aq;
145 \&
146 \& if ( blessed( $obj ) && $obj\->isa("Some::Class") ) {
147 \& ...
148 \& }
149 .Ve
150 .RE
151 .ie n .IP """$obj\->DOES( ROLE )""" 4
152 .el .IP "\f(CW$obj\->DOES( ROLE )\fR" 4
153 .IX Item "$obj->DOES( ROLE )"
154 .PD 0
155 .ie n .IP """CLASS\->DOES( ROLE )""" 4
156 .el .IP "\f(CWCLASS\->DOES( ROLE )\fR" 4
157 .IX Item "CLASS->DOES( ROLE )"
158 .PD
159 \&\f(CW\*(C`DOES\*(C'\fR checks if the object or class performs the role \f(CW\*(C`ROLE\*(C'\fR. A role is a
160 named group of specific behavior (often methods of particular names and
161 signatures), similar to a class, but not necessarily a complete class by
162 itself. For example, logging or serialization may be roles.
163 .Sp
164 \&\f(CW\*(C`DOES\*(C'\fR and \f(CW\*(C`isa\*(C'\fR are similar, in that if either is true, you know that the
165 object or class on which you call the method can perform specific behavior.
166 However, \f(CW\*(C`DOES\*(C'\fR is different from \f(CW\*(C`isa\*(C'\fR in that it does not care \fIhow\fR the
167 invocand performs the operations, merely that it does. (\f(CW\*(C`isa\*(C'\fR of course
168 mandates an inheritance relationship. Other relationships include aggregation,
169 delegation, and mocking.)
170 .Sp
171 By default, classes in Perl only perform the \f(CW\*(C`UNIVERSAL\*(C'\fR role, as well as the
172 role of all classes in their inheritance. In other words, by default \f(CW\*(C`DOES\*(C'\fR
173 responds identically to \f(CW\*(C`isa\*(C'\fR.
174 .Sp
175 There is a relationship between roles and classes, as each class implies the
176 existence of a role of the same name. There is also a relationship between
177 inheritance and roles, in that a subclass that inherits from an ancestor class
178 implicitly performs any roles its parent performs. Thus you can use \f(CW\*(C`DOES\*(C'\fR in
179 place of \f(CW\*(C`isa\*(C'\fR safely, as it will return true in all places where \f(CW\*(C`isa\*(C'\fR will
180 return true (provided that any overridden \f(CW\*(C`DOES\*(C'\fR \fIand\fR \f(CW\*(C`isa\*(C'\fR methods behave
181 appropriately).
182 .ie n .IP """$obj\->can( METHOD )""" 4
183 .el .IP "\f(CW$obj\->can( METHOD )\fR" 4
184 .IX Item "$obj->can( METHOD )"
185 .PD 0
186 .ie n .IP """CLASS\->can( METHOD )""" 4
187 .el .IP "\f(CWCLASS\->can( METHOD )\fR" 4
188 .IX Item "CLASS->can( METHOD )"
189 .ie n .IP """eval { VAL\->can( METHOD ) }""" 4
190 .el .IP "\f(CWeval { VAL\->can( METHOD ) }\fR" 4
191 .IX Item "eval { VAL->can( METHOD ) }"
192 .PD
193 \&\f(CW\*(C`can\*(C'\fR checks if the object or class has a method called \f(CW\*(C`METHOD\*(C'\fR. If it does,
194 then it returns a reference to the sub. If it does not, then it returns
195 \&\fIundef\fR. This includes methods inherited or imported by \f(CW$obj\fR, \f(CW\*(C`CLASS\*(C'\fR, or
196 \&\f(CW\*(C`VAL\*(C'\fR.
197 .Sp
198 \&\f(CW\*(C`can\*(C'\fR cannot know whether an object will be able to provide a method through
199 AUTOLOAD (unless the object\*(Aqs class has overridden \f(CW\*(C`can\*(C'\fR appropriately), so a
200 return value of \fIundef\fR does not necessarily mean the object will not be able
201 to handle the method call. To get around this some module authors use a forward
202 declaration (see perlsub) for methods they will handle via AUTOLOAD. For
203 such \*(Aqdummy\*(Aq subs, \f(CW\*(C`can\*(C'\fR will still return a code reference, which, when
204 called, will fall through to the AUTOLOAD. If no suitable AUTOLOAD is provided,
205 calling the coderef will cause an error.
206 .Sp
207 You may call \f(CW\*(C`can\*(C'\fR as a class (static) method or an object method.
208 .Sp
209 Again, the same rule about having a valid invocand applies \-\- use an \f(CW\*(C`eval\*(C'\fR
210 block or \f(CW\*(C`blessed\*(C'\fR if you need to be extra paranoid.
211 .ie n .IP """VERSION ( [ REQUIRE ] )""" 4
212 .el .IP "\f(CWVERSION ( [ REQUIRE ] )\fR" 4
213 .IX Item "VERSION ( [ REQUIRE ] )"
214 \&\f(CW\*(C`VERSION\*(C'\fR will return the value of the variable \f(CW$VERSION\fR in the
215 package the object is blessed into. If \f(CW\*(C`REQUIRE\*(C'\fR is given then
216 it will do a comparison and die if the package version is not
217 greater than or equal to \f(CW\*(C`REQUIRE\*(C'\fR, or if either \f(CW$VERSION\fR or \f(CW\*(C`REQUIRE\*(C'\fR
218 is not a "lax" version number (as defined by the version module).
219 .Sp
220 The return from \f(CW\*(C`VERSION\*(C'\fR will actually be the stringified version object
221 using the package \f(CW$VERSION\fR scalar, which is guaranteed to be equivalent
222 but may not be precisely the contents of the \f(CW$VERSION\fR scalar. If you want
223 the actual contents of \f(CW$VERSION\fR, use \f(CW$CLASS::VERSION\fR instead.
224 .Sp
225 \&\f(CW\*(C`VERSION\*(C'\fR can be called as either a class (static) method or an object
226 method.
227 .SH WARNINGS
228 .IX Header "WARNINGS"
229 \&\fBNOTE:\fR \f(CW\*(C`can\*(C'\fR directly uses Perl\*(Aqs internal code for method lookup, and
230 \&\f(CW\*(C`isa\*(C'\fR uses a very similar method and cache\-ing strategy. This may cause
231 strange effects if the Perl code dynamically changes \f(CW@ISA\fR in any package.
232 .PP
233 You may add other methods to the UNIVERSAL class via Perl or XS code.
234 You do not need to \f(CW\*(C`use UNIVERSAL\*(C'\fR to make these methods
235 available to your program (and you should not do so).
236 .SH EXPORTS
237 .IX Header "EXPORTS"
238 None.
239 .PP
240 Previous versions of this documentation suggested using \f(CW\*(C`isa\*(C'\fR as
241 a function to determine the type of a reference:
242 .PP
243 .Vb 2
244 \& $yes = UNIVERSAL::isa($h, "HASH");
245 \& $yes = UNIVERSAL::isa("Foo", "Bar");
246 .Ve
247 .PP
248 The problem is that this code would \fInever\fR call an overridden \f(CW\*(C`isa\*(C'\fR method in
249 any class. Instead, use \f(CW\*(C`reftype\*(C'\fR from Scalar::Util for the first case:
250 .PP
251 .Vb 1
252 \& use Scalar::Util \*(Aqreftype\*(Aq;
253 \&
254 \& $yes = reftype( $h ) eq "HASH";
255 .Ve
256 .PP
257 and the method form of \f(CW\*(C`isa\*(C'\fR for the second:
258 .PP
259 .Vb 1
260 \& $yes = Foo\->isa("Bar");
261 .Ve