| 1 |
.\" -*- mode: troff; coding: utf-8 -*- |
| 2 |
.\" Automatically generated by Pod::Man 5.0102 (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 |
.\" |
| 57 |
.IX Title "PERLOBJ 1" |
| 58 |
.TH PERLOBJ 1 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide" |
| 59 |
.\" For nroff, turn off justification. Always turn off hyphenation; it makes |
| 60 |
.\" way too many mistakes in technical documents. |
| 61 |
.if n .ad l |
| 62 |
.nh |
| 63 |
.SH NAME |
| 64 |
perlobj \- Perl object reference |
| 65 |
.IX Xref "object OOP" |
| 66 |
.SH DESCRIPTION |
| 67 |
.IX Header "DESCRIPTION" |
| 68 |
This document provides a reference for Perl's object orientation |
| 69 |
features. If you're looking for an introduction to object-oriented |
| 70 |
programming in Perl, please see perlootut. |
| 71 |
.PP |
| 72 |
In order to understand Perl objects, you first need to understand |
| 73 |
references in Perl. See perlreftut for details. |
| 74 |
.PP |
| 75 |
This document describes all of Perl's object-oriented (OO) features |
| 76 |
from the ground up. If you're just looking to write some |
| 77 |
object-oriented code of your own, you are probably better served by |
| 78 |
using one of the object systems from CPAN described in perlootut. |
| 79 |
.PP |
| 80 |
If you're looking to write your own object system, or you need to |
| 81 |
maintain code which implements objects from scratch then this document |
| 82 |
will help you understand exactly how Perl does object orientation. |
| 83 |
.PP |
| 84 |
There are a few basic principles which define object oriented Perl: |
| 85 |
.IP 1. 4 |
| 86 |
An object is simply a data structure that knows to which class it |
| 87 |
belongs. |
| 88 |
.IP 2. 4 |
| 89 |
A class is simply a package. A class provides methods that expect to |
| 90 |
operate on objects. |
| 91 |
.IP 3. 4 |
| 92 |
A method is simply a subroutine that expects a reference to an object |
| 93 |
(or a package name, for class methods) as the first argument. |
| 94 |
.PP |
| 95 |
Let's look at each of these principles in depth. |
| 96 |
.SS "An Object is Simply a Data Structure" |
| 97 |
.IX Xref "object bless constructor new" |
| 98 |
.IX Subsection "An Object is Simply a Data Structure" |
| 99 |
Unlike many other languages which support object orientation, Perl does |
| 100 |
not provide any special syntax for constructing an object. Objects are |
| 101 |
merely Perl data structures (hashes, arrays, scalars, filehandles, |
| 102 |
etc.) that have been explicitly associated with a particular class. |
| 103 |
.PP |
| 104 |
That explicit association is created by the built-in \f(CW\*(C`bless\*(C'\fR function, |
| 105 |
which is typically used within the \fIconstructor\fR subroutine of the |
| 106 |
class. |
| 107 |
.PP |
| 108 |
Here is a simple constructor: |
| 109 |
.PP |
| 110 |
.Vb 1 |
| 111 |
\& package File; |
| 112 |
\& |
| 113 |
\& sub new { |
| 114 |
\& my $class = shift; |
| 115 |
\& |
| 116 |
\& return bless {}, $class; |
| 117 |
\& } |
| 118 |
.Ve |
| 119 |
.PP |
| 120 |
The name \f(CW\*(C`new\*(C'\fR isn't special. We could name our constructor something |
| 121 |
else: |
| 122 |
.PP |
| 123 |
.Vb 1 |
| 124 |
\& package File; |
| 125 |
\& |
| 126 |
\& sub load { |
| 127 |
\& my $class = shift; |
| 128 |
\& |
| 129 |
\& return bless {}, $class; |
| 130 |
\& } |
| 131 |
.Ve |
| 132 |
.PP |
| 133 |
The modern convention for OO modules is to always use \f(CW\*(C`new\*(C'\fR as the |
| 134 |
name for the constructor, but there is no requirement to do so. Any |
| 135 |
subroutine that blesses a data structure into a class is a valid |
| 136 |
constructor in Perl. |
| 137 |
.PP |
| 138 |
In the previous examples, the \f(CW\*(C`{}\*(C'\fR code creates a reference to an |
| 139 |
empty anonymous hash. The \f(CW\*(C`bless\*(C'\fR function then takes that reference |
| 140 |
and associates the hash with the class in \f(CW$class\fR. In the simplest |
| 141 |
case, the \f(CW$class\fR variable will end up containing the string "File". |
| 142 |
.PP |
| 143 |
We can also use a variable to store a reference to the data structure |
| 144 |
that is being blessed as our object: |
| 145 |
.PP |
| 146 |
.Vb 2 |
| 147 |
\& sub new { |
| 148 |
\& my $class = shift; |
| 149 |
\& |
| 150 |
\& my $self = {}; |
| 151 |
\& bless $self, $class; |
| 152 |
\& |
| 153 |
\& return $self; |
| 154 |
\& } |
| 155 |
.Ve |
| 156 |
.PP |
| 157 |
Once we've blessed the hash referred to by \f(CW$self\fR we can start |
| 158 |
calling methods on it. This is useful if you want to put object |
| 159 |
initialization in its own separate method: |
| 160 |
.PP |
| 161 |
.Vb 2 |
| 162 |
\& sub new { |
| 163 |
\& my $class = shift; |
| 164 |
\& |
| 165 |
\& my $self = {}; |
| 166 |
\& bless $self, $class; |
| 167 |
\& |
| 168 |
\& $self\->_initialize(); |
| 169 |
\& |
| 170 |
\& return $self; |
| 171 |
\& } |
| 172 |
.Ve |
| 173 |
.PP |
| 174 |
Since the object is also a hash, you can treat it as one, using it to |
| 175 |
store data associated with the object. Typically, code inside the class |
| 176 |
can treat the hash as an accessible data structure, while code outside |
| 177 |
the class should always treat the object as opaque. This is called |
| 178 |
\&\fBencapsulation\fR. Encapsulation means that the user of an object does |
| 179 |
not have to know how it is implemented. The user simply calls |
| 180 |
documented methods on the object. |
| 181 |
.PP |
| 182 |
Note, however, that (unlike most other OO languages) Perl does not |
| 183 |
ensure or enforce encapsulation in any way. If you want objects to |
| 184 |
actually \fIbe\fR opaque you need to arrange for that yourself. This can |
| 185 |
be done in a variety of ways, including using "Inside-Out objects" |
| 186 |
or modules from CPAN. |
| 187 |
.PP |
| 188 |
\fIObjects Are Blessed; Variables Are Not\fR |
| 189 |
.IX Subsection "Objects Are Blessed; Variables Are Not" |
| 190 |
.PP |
| 191 |
When we bless something, we are not blessing the variable which |
| 192 |
contains a reference to that thing, nor are we blessing the reference |
| 193 |
that the variable stores; we are blessing the thing that the variable |
| 194 |
refers to (sometimes known as the \fIreferent\fR). This is best |
| 195 |
demonstrated with this code: |
| 196 |
.PP |
| 197 |
.Vb 1 |
| 198 |
\& use Scalar::Util \*(Aqblessed\*(Aq; |
| 199 |
\& |
| 200 |
\& my $foo = {}; |
| 201 |
\& my $bar = $foo; |
| 202 |
\& |
| 203 |
\& bless $foo, \*(AqClass\*(Aq; |
| 204 |
\& print blessed( $bar ) // \*(Aqnot blessed\*(Aq; # prints "Class" |
| 205 |
\& |
| 206 |
\& $bar = "some other value"; |
| 207 |
\& print blessed( $bar ) // \*(Aqnot blessed\*(Aq; # prints "not blessed" |
| 208 |
.Ve |
| 209 |
.PP |
| 210 |
When we call \f(CW\*(C`bless\*(C'\fR on a variable, we are actually blessing the |
| 211 |
underlying data structure that the variable refers to. We are not |
| 212 |
blessing the reference itself, nor the variable that contains that |
| 213 |
reference. That's why the second call to \f(CWblessed( $bar )\fR returns |
| 214 |
false. At that point \f(CW$bar\fR is no longer storing a reference to an |
| 215 |
object. |
| 216 |
.PP |
| 217 |
You will sometimes see older books or documentation mention "blessing a |
| 218 |
reference" or describe an object as a "blessed reference", but this is |
| 219 |
incorrect. It isn't the reference that is blessed as an object; it's |
| 220 |
the thing the reference refers to (i.e. the referent). |
| 221 |
.SS "A Class is Simply a Package" |
| 222 |
.IX Xref "class package @ISA inheritance" |
| 223 |
.IX Subsection "A Class is Simply a Package" |
| 224 |
Perl does not provide any special syntax for class definitions. A |
| 225 |
package is simply a namespace containing variables and subroutines. The |
| 226 |
only difference is that in a class, the subroutines may expect a |
| 227 |
reference to an object or the name of a class as the first argument. |
| 228 |
This is purely a matter of convention, so a class may contain both |
| 229 |
methods and subroutines which \fIdon't\fR operate on an object or class. |
| 230 |
.PP |
| 231 |
Each package contains a special array called \f(CW@ISA\fR. The \f(CW@ISA\fR array |
| 232 |
contains a list of that class's parent classes, if any. This array is |
| 233 |
examined when Perl does method resolution, which we will cover later. |
| 234 |
.PP |
| 235 |
Calling methods from a package means it must be loaded, of course, so |
| 236 |
you will often want to load a module and add it to \f(CW@ISA\fR at the same |
| 237 |
time. You can do so in a single step using the parent pragma. |
| 238 |
(In older code you may encounter the base pragma, which is nowadays |
| 239 |
discouraged except when you have to work with the equally discouraged |
| 240 |
fields pragma.) |
| 241 |
.PP |
| 242 |
However the parent classes are set, the package's \f(CW@ISA\fR variable will |
| 243 |
contain a list of those parents. This is simply a list of scalars, each |
| 244 |
of which is a string that corresponds to a package name. |
| 245 |
.PP |
| 246 |
All classes inherit from the UNIVERSAL class implicitly. The |
| 247 |
UNIVERSAL class is implemented by the Perl core, and provides |
| 248 |
several default methods, such as \f(CWisa()\fR, \f(CWcan()\fR, and \f(CWVERSION()\fR. |
| 249 |
The \f(CW\*(C`UNIVERSAL\*(C'\fR class will \fInever\fR appear in a package's \f(CW@ISA\fR |
| 250 |
variable. |
| 251 |
.PP |
| 252 |
Perl \fIonly\fR provides method inheritance as a built-in feature. |
| 253 |
Attribute inheritance is left up the class to implement. See the |
| 254 |
"Writing Accessors" section for details. |
| 255 |
.SS "A Method is Simply a Subroutine" |
| 256 |
.IX Xref "method" |
| 257 |
.IX Subsection "A Method is Simply a Subroutine" |
| 258 |
Perl does not provide any special syntax for defining a method. A |
| 259 |
method is simply a regular subroutine, and is declared with \f(CW\*(C`sub\*(C'\fR. |
| 260 |
What makes a method special is that it expects to receive either an |
| 261 |
object or a class name as its first argument. |
| 262 |
.PP |
| 263 |
Perl \fIdoes\fR provide special syntax for method invocation, the \f(CW\*(C`\->\*(C'\fR operator. We will cover this in more detail later. |
| 264 |
.PP |
| 265 |
Most methods you write will expect to operate on objects: |
| 266 |
.PP |
| 267 |
.Vb 2 |
| 268 |
\& sub save { |
| 269 |
\& my $self = shift; |
| 270 |
\& |
| 271 |
\& open my $fh, \*(Aq>\*(Aq, $self\->path() or die $!; |
| 272 |
\& print {$fh} $self\->data() or die $!; |
| 273 |
\& close $fh or die $!; |
| 274 |
\& } |
| 275 |
.Ve |
| 276 |
.SS "Method Invocation" |
| 277 |
.IX Xref "invocation method arrow ->" |
| 278 |
.IX Subsection "Method Invocation" |
| 279 |
Calling a method on an object is written as \f(CW\*(C`$object\->method\*(C'\fR. |
| 280 |
.PP |
| 281 |
The left hand side of the method invocation (or arrow) operator is the |
| 282 |
object (or class name), and the right hand side is the method name. |
| 283 |
.PP |
| 284 |
.Vb 2 |
| 285 |
\& my $pod = File\->new( \*(Aqperlobj.pod\*(Aq, $data ); |
| 286 |
\& $pod\->save(); |
| 287 |
.Ve |
| 288 |
.PP |
| 289 |
The \f(CW\*(C`\->\*(C'\fR syntax is also used when dereferencing a reference. It |
| 290 |
looks like the same operator, but these are two different operations. |
| 291 |
.PP |
| 292 |
When you call a method, the thing on the left side of the arrow is |
| 293 |
passed as the first argument to the method. That means when we call \f(CW\*(C`Critter\->new()\*(C'\fR, the \f(CWnew()\fR method receives the string \f(CW"Critter"\fR |
| 294 |
as its first argument. When we call \f(CW\*(C`$fred\->speak()\*(C'\fR, the \f(CW$fred\fR |
| 295 |
variable is passed as the first argument to \f(CWspeak()\fR. |
| 296 |
.PP |
| 297 |
Just as with any Perl subroutine, all of the arguments passed in \f(CW@_\fR |
| 298 |
are aliases to the original argument. This includes the object itself. |
| 299 |
If you assign directly to \f(CW$_[0]\fR you will change the contents of the |
| 300 |
variable that holds the reference to the object. We recommend that you |
| 301 |
don't do this unless you know exactly what you're doing. |
| 302 |
.PP |
| 303 |
Perl knows what package the method is in by looking at the left side of |
| 304 |
the arrow. If the left hand side is a package name, it looks for the |
| 305 |
method in that package. If the left hand side is an object, then Perl |
| 306 |
looks for the method in the package that the object has been blessed |
| 307 |
into. |
| 308 |
.PP |
| 309 |
If the left hand side is neither a package name nor an object, then the |
| 310 |
method call will cause an error, but see the section on "Method Call |
| 311 |
Variations" for more nuances. |
| 312 |
.SS Inheritance |
| 313 |
.IX Xref "inheritance" |
| 314 |
.IX Subsection "Inheritance" |
| 315 |
We already talked about the special \f(CW@ISA\fR array and the parent |
| 316 |
pragma. |
| 317 |
.PP |
| 318 |
When a class inherits from another class, any methods defined in the |
| 319 |
parent class are available to the child class. If you attempt to call a |
| 320 |
method on an object that isn't defined in its own class, Perl will also |
| 321 |
look for that method in any parent classes it may have. |
| 322 |
.PP |
| 323 |
.Vb 2 |
| 324 |
\& package File::MP3; |
| 325 |
\& use parent \*(AqFile\*(Aq; # sets @File::MP3::ISA = (\*(AqFile\*(Aq); |
| 326 |
\& |
| 327 |
\& my $mp3 = File::MP3\->new( \*(AqAndvari.mp3\*(Aq, $data ); |
| 328 |
\& $mp3\->save(); |
| 329 |
.Ve |
| 330 |
.PP |
| 331 |
Since we didn't define a \f(CWsave()\fR method in the \f(CW\*(C`File::MP3\*(C'\fR class, |
| 332 |
Perl will look at the \f(CW\*(C`File::MP3\*(C'\fR class's parent classes to find the |
| 333 |
\&\f(CWsave()\fR method. If Perl cannot find a \f(CWsave()\fR method anywhere in |
| 334 |
the inheritance hierarchy, it will die. |
| 335 |
.PP |
| 336 |
In this case, it finds a \f(CWsave()\fR method in the \f(CW\*(C`File\*(C'\fR class. Note |
| 337 |
that the object passed to \f(CWsave()\fR in this case is still a |
| 338 |
\&\f(CW\*(C`File::MP3\*(C'\fR object, even though the method is found in the \f(CW\*(C`File\*(C'\fR |
| 339 |
class. |
| 340 |
.PP |
| 341 |
We can override a parent's method in a child class. When we do so, we |
| 342 |
can still call the parent class's method with the \f(CW\*(C`SUPER\*(C'\fR |
| 343 |
pseudo-class. |
| 344 |
.PP |
| 345 |
.Vb 2 |
| 346 |
\& sub save { |
| 347 |
\& my $self = shift; |
| 348 |
\& |
| 349 |
\& say \*(AqPrepare to rock\*(Aq; |
| 350 |
\& $self\->SUPER::save(); |
| 351 |
\& } |
| 352 |
.Ve |
| 353 |
.PP |
| 354 |
The \f(CW\*(C`SUPER\*(C'\fR modifier can \fIonly\fR be used for method calls. You can't |
| 355 |
use it for regular subroutine calls or class methods: |
| 356 |
.PP |
| 357 |
.Vb 1 |
| 358 |
\& SUPER::save($thing); # FAIL: looks for save() sub in package SUPER |
| 359 |
\& |
| 360 |
\& SUPER\->save($thing); # FAIL: looks for save() method in class |
| 361 |
\& # SUPER |
| 362 |
\& |
| 363 |
\& $thing\->SUPER::save(); # Okay: looks for save() method in parent |
| 364 |
\& # classes |
| 365 |
.Ve |
| 366 |
.PP |
| 367 |
\fIHow SUPER is Resolved\fR |
| 368 |
.IX Xref "SUPER" |
| 369 |
.IX Subsection "How SUPER is Resolved" |
| 370 |
.PP |
| 371 |
The \f(CW\*(C`SUPER\*(C'\fR pseudo-class is resolved from the package where the call |
| 372 |
is made. It is \fInot\fR resolved based on the object's class. This is |
| 373 |
important, because it lets methods at different levels within a deep |
| 374 |
inheritance hierarchy each correctly call their respective parent |
| 375 |
methods. |
| 376 |
.PP |
| 377 |
.Vb 1 |
| 378 |
\& package A; |
| 379 |
\& |
| 380 |
\& sub new { |
| 381 |
\& return bless {}, shift; |
| 382 |
\& } |
| 383 |
\& |
| 384 |
\& sub speak { |
| 385 |
\& my $self = shift; |
| 386 |
\& |
| 387 |
\& say \*(AqA\*(Aq; |
| 388 |
\& } |
| 389 |
\& |
| 390 |
\& package B; |
| 391 |
\& |
| 392 |
\& use parent \-norequire, \*(AqA\*(Aq; |
| 393 |
\& |
| 394 |
\& sub speak { |
| 395 |
\& my $self = shift; |
| 396 |
\& |
| 397 |
\& $self\->SUPER::speak(); |
| 398 |
\& |
| 399 |
\& say \*(AqB\*(Aq; |
| 400 |
\& } |
| 401 |
\& |
| 402 |
\& package C; |
| 403 |
\& |
| 404 |
\& use parent \-norequire, \*(AqB\*(Aq; |
| 405 |
\& |
| 406 |
\& sub speak { |
| 407 |
\& my $self = shift; |
| 408 |
\& |
| 409 |
\& $self\->SUPER::speak(); |
| 410 |
\& |
| 411 |
\& say \*(AqC\*(Aq; |
| 412 |
\& } |
| 413 |
\& |
| 414 |
\& my $c = C\->new(); |
| 415 |
\& $c\->speak(); |
| 416 |
.Ve |
| 417 |
.PP |
| 418 |
In this example, we will get the following output: |
| 419 |
.PP |
| 420 |
.Vb 3 |
| 421 |
\& A |
| 422 |
\& B |
| 423 |
\& C |
| 424 |
.Ve |
| 425 |
.PP |
| 426 |
This demonstrates how \f(CW\*(C`SUPER\*(C'\fR is resolved. Even though the object is |
| 427 |
blessed into the \f(CW\*(C`C\*(C'\fR class, the \f(CWspeak()\fR method in the \f(CW\*(C`B\*(C'\fR class |
| 428 |
can still call \f(CWSUPER::speak()\fR and expect it to correctly look in the |
| 429 |
parent class of \f(CW\*(C`B\*(C'\fR (i.e the class the method call is in), not in the |
| 430 |
parent class of \f(CW\*(C`C\*(C'\fR (i.e. the class the object belongs to). |
| 431 |
.PP |
| 432 |
There are rare cases where this package-based resolution can be a |
| 433 |
problem. If you copy a subroutine from one package to another, \f(CW\*(C`SUPER\*(C'\fR |
| 434 |
resolution will be done based on the original package. |
| 435 |
.PP |
| 436 |
\fIMultiple Inheritance\fR |
| 437 |
.IX Xref "multiple inheritance" |
| 438 |
.IX Subsection "Multiple Inheritance" |
| 439 |
.PP |
| 440 |
Multiple inheritance often indicates a design problem, but Perl always |
| 441 |
gives you enough rope to hang yourself with if you ask for it. |
| 442 |
.PP |
| 443 |
To declare multiple parents, you simply need to pass multiple class |
| 444 |
names to \f(CW\*(C`use parent\*(C'\fR: |
| 445 |
.PP |
| 446 |
.Vb 1 |
| 447 |
\& package MultiChild; |
| 448 |
\& |
| 449 |
\& use parent \*(AqParent1\*(Aq, \*(AqParent2\*(Aq; |
| 450 |
.Ve |
| 451 |
.PP |
| 452 |
\fIMethod Resolution Order\fR |
| 453 |
.IX Xref "method resolution order mro" |
| 454 |
.IX Subsection "Method Resolution Order" |
| 455 |
.PP |
| 456 |
Method resolution order only matters in the case of multiple |
| 457 |
inheritance. In the case of single inheritance, Perl simply looks up |
| 458 |
the inheritance chain to find a method: |
| 459 |
.PP |
| 460 |
.Vb 5 |
| 461 |
\& Grandparent |
| 462 |
\& | |
| 463 |
\& Parent |
| 464 |
\& | |
| 465 |
\& Child |
| 466 |
.Ve |
| 467 |
.PP |
| 468 |
If we call a method on a \f(CW\*(C`Child\*(C'\fR object and that method is not defined |
| 469 |
in the \f(CW\*(C`Child\*(C'\fR class, Perl will look for that method in the \f(CW\*(C`Parent\*(C'\fR |
| 470 |
class and then, if necessary, in the \f(CW\*(C`Grandparent\*(C'\fR class. |
| 471 |
.PP |
| 472 |
If Perl cannot find the method in any of these classes, it will die |
| 473 |
with an error message. |
| 474 |
.PP |
| 475 |
When a class has multiple parents, the method lookup order becomes more |
| 476 |
complicated. |
| 477 |
.PP |
| 478 |
By default, Perl does a depth-first left-to-right search for a method. |
| 479 |
That means it starts with the first parent in the \f(CW@ISA\fR array, and |
| 480 |
then searches all of its parents, grandparents, etc. If it fails to |
| 481 |
find the method, it then goes to the next parent in the original |
| 482 |
class's \f(CW@ISA\fR array and searches from there. |
| 483 |
.PP |
| 484 |
.Vb 7 |
| 485 |
\& SharedGreatGrandParent |
| 486 |
\& / \e |
| 487 |
\& PaternalGrandparent MaternalGrandparent |
| 488 |
\& \e / |
| 489 |
\& Father Mother |
| 490 |
\& \e / |
| 491 |
\& Child |
| 492 |
.Ve |
| 493 |
.PP |
| 494 |
So given the diagram above, Perl will search \f(CW\*(C`Child\*(C'\fR, \f(CW\*(C`Father\*(C'\fR, |
| 495 |
\&\f(CW\*(C`PaternalGrandparent\*(C'\fR, \f(CW\*(C`SharedGreatGrandParent\*(C'\fR, \f(CW\*(C`Mother\*(C'\fR, and |
| 496 |
finally \f(CW\*(C`MaternalGrandparent\*(C'\fR. This may be a problem because now we're |
| 497 |
looking in \f(CW\*(C`SharedGreatGrandParent\*(C'\fR \fIbefore\fR we've checked all its |
| 498 |
derived classes (i.e. before we tried \f(CW\*(C`Mother\*(C'\fR and |
| 499 |
\&\f(CW\*(C`MaternalGrandparent\*(C'\fR). |
| 500 |
.PP |
| 501 |
It is possible to ask for a different method resolution order with the |
| 502 |
mro pragma. |
| 503 |
.PP |
| 504 |
.Vb 1 |
| 505 |
\& package Child; |
| 506 |
\& |
| 507 |
\& use mro \*(Aqc3\*(Aq; |
| 508 |
\& use parent \*(AqFather\*(Aq, \*(AqMother\*(Aq; |
| 509 |
.Ve |
| 510 |
.PP |
| 511 |
This pragma lets you switch to the "C3" resolution order. In simple |
| 512 |
terms, "C3" order ensures that shared parent classes are never searched |
| 513 |
before child classes, so Perl will now search: \f(CW\*(C`Child\*(C'\fR, \f(CW\*(C`Father\*(C'\fR, |
| 514 |
\&\f(CW\*(C`PaternalGrandparent\*(C'\fR, \f(CW\*(C`Mother\*(C'\fR \f(CW\*(C`MaternalGrandparent\*(C'\fR, and finally |
| 515 |
\&\f(CW\*(C`SharedGreatGrandParent\*(C'\fR. Note however that this is not |
| 516 |
"breadth-first" searching: All the \f(CW\*(C`Father\*(C'\fR ancestors (except the |
| 517 |
common ancestor) are searched before any of the \f(CW\*(C`Mother\*(C'\fR ancestors are |
| 518 |
considered. |
| 519 |
.PP |
| 520 |
The C3 order also lets you call methods in sibling classes with the |
| 521 |
\&\f(CW\*(C`next\*(C'\fR pseudo-class. See the mro documentation for more details on |
| 522 |
this feature. |
| 523 |
.PP |
| 524 |
\fIMethod Resolution Caching\fR |
| 525 |
.IX Subsection "Method Resolution Caching" |
| 526 |
.PP |
| 527 |
When Perl searches for a method, it caches the lookup so that future |
| 528 |
calls to the method do not need to search for it again. Changing a |
| 529 |
class's parent class or adding subroutines to a class will invalidate |
| 530 |
the cache for that class. |
| 531 |
.PP |
| 532 |
The mro pragma provides some functions for manipulating the method |
| 533 |
cache directly. |
| 534 |
.SS "Writing Constructors" |
| 535 |
.IX Xref "constructor" |
| 536 |
.IX Subsection "Writing Constructors" |
| 537 |
As we mentioned earlier, Perl provides no special constructor syntax. |
| 538 |
This means that a class must implement its own constructor. A |
| 539 |
constructor is simply a class method that returns a reference to a new |
| 540 |
object. |
| 541 |
.PP |
| 542 |
The constructor can also accept additional parameters that define the |
| 543 |
object. Let's write a real constructor for the \f(CW\*(C`File\*(C'\fR class we used |
| 544 |
earlier: |
| 545 |
.PP |
| 546 |
.Vb 1 |
| 547 |
\& package File; |
| 548 |
\& |
| 549 |
\& sub new { |
| 550 |
\& my $class = shift; |
| 551 |
\& my ( $path, $data ) = @_; |
| 552 |
\& |
| 553 |
\& my $self = bless { |
| 554 |
\& path => $path, |
| 555 |
\& data => $data, |
| 556 |
\& }, $class; |
| 557 |
\& |
| 558 |
\& return $self; |
| 559 |
\& } |
| 560 |
.Ve |
| 561 |
.PP |
| 562 |
As you can see, we've stored the path and file data in the object |
| 563 |
itself. Remember, under the hood, this object is still just a hash. |
| 564 |
Later, we'll write accessors to manipulate this data. |
| 565 |
.PP |
| 566 |
For our \f(CW\*(C`File::MP3\*(C'\fR class, we can check to make sure that the path |
| 567 |
we're given ends with ".mp3": |
| 568 |
.PP |
| 569 |
.Vb 1 |
| 570 |
\& package File::MP3; |
| 571 |
\& |
| 572 |
\& sub new { |
| 573 |
\& my $class = shift; |
| 574 |
\& my ( $path, $data ) = @_; |
| 575 |
\& |
| 576 |
\& die "You cannot create a File::MP3 without an mp3 extension\en" |
| 577 |
\& unless $path =~ /\e.mp3\ez/; |
| 578 |
\& |
| 579 |
\& return $class\->SUPER::new(@_); |
| 580 |
\& } |
| 581 |
.Ve |
| 582 |
.PP |
| 583 |
This constructor lets its parent class do the actual object |
| 584 |
construction. |
| 585 |
.SS Attributes |
| 586 |
.IX Xref "attribute" |
| 587 |
.IX Subsection "Attributes" |
| 588 |
An attribute is a piece of data belonging to a particular object. |
| 589 |
Unlike most object-oriented languages, Perl provides no special syntax |
| 590 |
or support for declaring and manipulating attributes. |
| 591 |
.PP |
| 592 |
Attributes are often stored in the object itself. For example, if the |
| 593 |
object is an anonymous hash, we can store the attribute values in the |
| 594 |
hash using the attribute name as the key. |
| 595 |
.PP |
| 596 |
While it's possible to refer directly to these hash keys outside of the |
| 597 |
class, it's considered a best practice to wrap all access to the |
| 598 |
attribute with accessor methods. |
| 599 |
.PP |
| 600 |
This has several advantages. Accessors make it easier to change the |
| 601 |
implementation of an object later while still preserving the original |
| 602 |
API. |
| 603 |
.PP |
| 604 |
An accessor lets you add additional code around attribute access. For |
| 605 |
example, you could apply a default to an attribute that wasn't set in |
| 606 |
the constructor, or you could validate that a new value for the |
| 607 |
attribute is acceptable. |
| 608 |
.PP |
| 609 |
Finally, using accessors makes inheritance much simpler. Subclasses can |
| 610 |
use the accessors rather than having to know how a parent class is |
| 611 |
implemented internally. |
| 612 |
.PP |
| 613 |
\fIWriting Accessors\fR |
| 614 |
.IX Xref "accessor" |
| 615 |
.IX Subsection "Writing Accessors" |
| 616 |
.PP |
| 617 |
As with constructors, Perl provides no special accessor declaration |
| 618 |
syntax, so classes must provide explicitly written accessor methods. |
| 619 |
There are two common types of accessors, read-only and read-write. |
| 620 |
.PP |
| 621 |
A simple read-only accessor simply gets the value of a single |
| 622 |
attribute: |
| 623 |
.PP |
| 624 |
.Vb 2 |
| 625 |
\& sub path { |
| 626 |
\& my $self = shift; |
| 627 |
\& |
| 628 |
\& return $self\->{path}; |
| 629 |
\& } |
| 630 |
.Ve |
| 631 |
.PP |
| 632 |
A read-write accessor will allow the caller to set the value as well as |
| 633 |
get it: |
| 634 |
.PP |
| 635 |
.Vb 2 |
| 636 |
\& sub path { |
| 637 |
\& my $self = shift; |
| 638 |
\& |
| 639 |
\& if (@_) { |
| 640 |
\& $self\->{path} = shift; |
| 641 |
\& } |
| 642 |
\& |
| 643 |
\& return $self\->{path}; |
| 644 |
\& } |
| 645 |
.Ve |
| 646 |
.SS "An Aside About Smarter and Safer Code" |
| 647 |
.IX Subsection "An Aside About Smarter and Safer Code" |
| 648 |
Our constructor and accessors are not very smart. They don't check that |
| 649 |
a \f(CW$path\fR is defined, nor do they check that a \f(CW$path\fR is a valid |
| 650 |
filesystem path. |
| 651 |
.PP |
| 652 |
Doing these checks by hand can quickly become tedious. Writing a bunch |
| 653 |
of accessors by hand is also incredibly tedious. There are a lot of |
| 654 |
modules on CPAN that can help you write safer and more concise code, |
| 655 |
including the modules we recommend in perlootut. |
| 656 |
.SS "Method Call Variations" |
| 657 |
.IX Xref "method" |
| 658 |
.IX Subsection "Method Call Variations" |
| 659 |
Perl supports several other ways to call methods besides the \f(CW\*(C`$object\->method()\*(C'\fR usage we've seen so far. |
| 660 |
.PP |
| 661 |
\fIMethod Names with a Fully Qualified Name\fR |
| 662 |
.IX Subsection "Method Names with a Fully Qualified Name" |
| 663 |
.PP |
| 664 |
Perl allows you to call methods using their fully qualified name (the |
| 665 |
package and method name): |
| 666 |
.PP |
| 667 |
.Vb 2 |
| 668 |
\& my $mp3 = File::MP3\->new( \*(AqRegin.mp3\*(Aq, $data ); |
| 669 |
\& $mp3\->File::save(); |
| 670 |
.Ve |
| 671 |
.PP |
| 672 |
When you call a fully qualified method name like \f(CW\*(C`File::save\*(C'\fR, the method |
| 673 |
resolution search for the \f(CW\*(C`save\*(C'\fR method starts in the \f(CW\*(C`File\*(C'\fR class, |
| 674 |
skipping any \f(CW\*(C`save\*(C'\fR method the \f(CW\*(C`File::MP3\*(C'\fR class may have defined. It |
| 675 |
still searches the \f(CW\*(C`File\*(C'\fR class's parents if necessary. |
| 676 |
.PP |
| 677 |
While this feature is most commonly used to explicitly call methods |
| 678 |
inherited from an ancestor class, there is no technical restriction |
| 679 |
that enforces this: |
| 680 |
.PP |
| 681 |
.Vb 2 |
| 682 |
\& my $obj = Tree\->new(); |
| 683 |
\& $obj\->Dog::bark(); |
| 684 |
.Ve |
| 685 |
.PP |
| 686 |
This calls the \f(CW\*(C`bark\*(C'\fR method from class \f(CW\*(C`Dog\*(C'\fR on an object of class |
| 687 |
\&\f(CW\*(C`Tree\*(C'\fR, even if the two classes are completely unrelated. Use this |
| 688 |
with great care. |
| 689 |
.PP |
| 690 |
The \f(CW\*(C`SUPER\*(C'\fR pseudo-class that was described earlier is \fInot\fR the same |
| 691 |
as calling a method with a fully-qualified name. See the earlier |
| 692 |
"Inheritance" section for details. |
| 693 |
.PP |
| 694 |
\fIMethod Names as Strings\fR |
| 695 |
.IX Subsection "Method Names as Strings" |
| 696 |
.PP |
| 697 |
Perl lets you use a scalar variable containing a string as a method |
| 698 |
name: |
| 699 |
.PP |
| 700 |
.Vb 1 |
| 701 |
\& my $file = File\->new( $path, $data ); |
| 702 |
\& |
| 703 |
\& my $method = \*(Aqsave\*(Aq; |
| 704 |
\& $file\->$method(); |
| 705 |
.Ve |
| 706 |
.PP |
| 707 |
This works exactly like calling \f(CW\*(C`$file\->save()\*(C'\fR. This can be very |
| 708 |
useful for writing dynamic code. For example, it allows you to pass a |
| 709 |
method name to be called as a parameter to another method. |
| 710 |
.PP |
| 711 |
\fIClass Names as Strings\fR |
| 712 |
.IX Subsection "Class Names as Strings" |
| 713 |
.PP |
| 714 |
Perl also lets you use a scalar containing a string as a class name: |
| 715 |
.PP |
| 716 |
.Vb 1 |
| 717 |
\& my $class = \*(AqFile\*(Aq; |
| 718 |
\& |
| 719 |
\& my $file = $class\->new( $path, $data ); |
| 720 |
.Ve |
| 721 |
.PP |
| 722 |
Again, this allows for very dynamic code. |
| 723 |
.PP |
| 724 |
\fISubroutine References as Methods\fR |
| 725 |
.IX Subsection "Subroutine References as Methods" |
| 726 |
.PP |
| 727 |
You can also use a subroutine reference as a method: |
| 728 |
.PP |
| 729 |
.Vb 2 |
| 730 |
\& my $sub = sub { |
| 731 |
\& my $self = shift; |
| 732 |
\& |
| 733 |
\& $self\->save(); |
| 734 |
\& }; |
| 735 |
\& |
| 736 |
\& $file\->$sub(); |
| 737 |
.Ve |
| 738 |
.PP |
| 739 |
This is exactly equivalent to writing \f(CW$sub\->($file)\fR. You may see |
| 740 |
this idiom in the wild combined with a call to \f(CW\*(C`can\*(C'\fR: |
| 741 |
.PP |
| 742 |
.Vb 3 |
| 743 |
\& if ( my $meth = $object\->can(\*(Aqfoo\*(Aq) ) { |
| 744 |
\& $object\->$meth(); |
| 745 |
\& } |
| 746 |
.Ve |
| 747 |
.PP |
| 748 |
\fIDereferencing Method Call\fR |
| 749 |
.IX Subsection "Dereferencing Method Call" |
| 750 |
.PP |
| 751 |
Perl also lets you use a dereferenced scalar reference in a method |
| 752 |
call. That's a mouthful, so let's look at some code: |
| 753 |
.PP |
| 754 |
.Vb 4 |
| 755 |
\& $file\->${ \e\*(Aqsave\*(Aq }; |
| 756 |
\& $file\->${ returns_scalar_ref() }; |
| 757 |
\& $file\->${ \e( returns_scalar() ) }; |
| 758 |
\& $file\->${ returns_ref_to_sub_ref() }; |
| 759 |
.Ve |
| 760 |
.PP |
| 761 |
This works if the dereference produces a string \fIor\fR a subroutine |
| 762 |
reference. |
| 763 |
.PP |
| 764 |
\fIMethod Calls on Filehandles\fR |
| 765 |
.IX Subsection "Method Calls on Filehandles" |
| 766 |
.PP |
| 767 |
Under the hood, Perl filehandles are instances of the \f(CW\*(C`IO::Handle\*(C'\fR or |
| 768 |
\&\f(CW\*(C`IO::File\*(C'\fR class. Once you have an open filehandle, you can call |
| 769 |
methods on it. Additionally, you can call methods on the \f(CW\*(C`STDIN\*(C'\fR, |
| 770 |
\&\f(CW\*(C`STDOUT\*(C'\fR, and \f(CW\*(C`STDERR\*(C'\fR filehandles. |
| 771 |
.PP |
| 772 |
.Vb 3 |
| 773 |
\& open my $fh, \*(Aq>\*(Aq, \*(Aqpath/to/file\*(Aq; |
| 774 |
\& $fh\->autoflush(); |
| 775 |
\& $fh\->print(\*(Aqcontent\*(Aq); |
| 776 |
\& |
| 777 |
\& STDOUT\->autoflush(); |
| 778 |
.Ve |
| 779 |
.SS "Invoking Class Methods" |
| 780 |
.IX Xref "invocation" |
| 781 |
.IX Subsection "Invoking Class Methods" |
| 782 |
Because Perl allows you to use barewords for package names and |
| 783 |
subroutine names, it sometimes interprets a bareword's meaning |
| 784 |
incorrectly. For example, the construct \f(CW\*(C`Class\->new()\*(C'\fR can be |
| 785 |
interpreted as either \f(CW\*(C`\*(AqClass\*(Aq\->new()\*(C'\fR or \f(CW\*(C`Class()\->new()\*(C'\fR. |
| 786 |
In English, that second interpretation reads as "call a subroutine |
| 787 |
named \fBClass()\fR, then call \fBnew()\fR as a method on the return value of |
| 788 |
\&\fBClass()\fR". If there is a subroutine named \f(CWClass()\fR in the current |
| 789 |
namespace, Perl will always interpret \f(CW\*(C`Class\->new()\*(C'\fR as the second |
| 790 |
alternative: a call to \f(CWnew()\fR on the object returned by a call to |
| 791 |
\&\f(CWClass()\fR |
| 792 |
.PP |
| 793 |
You can force Perl to use the first interpretation (i.e. as a method |
| 794 |
call on the class named "Class") in two ways. First, you can append a |
| 795 |
\&\f(CW\*(C`::\*(C'\fR to the class name: |
| 796 |
.PP |
| 797 |
.Vb 1 |
| 798 |
\& Class::\->new() |
| 799 |
.Ve |
| 800 |
.PP |
| 801 |
Perl will always interpret this as a method call. |
| 802 |
.PP |
| 803 |
Alternatively, you can quote the class name: |
| 804 |
.PP |
| 805 |
.Vb 1 |
| 806 |
\& \*(AqClass\*(Aq\->new() |
| 807 |
.Ve |
| 808 |
.PP |
| 809 |
Of course, if the class name is in a scalar Perl will do the right |
| 810 |
thing as well: |
| 811 |
.PP |
| 812 |
.Vb 2 |
| 813 |
\& my $class = \*(AqClass\*(Aq; |
| 814 |
\& $class\->new(); |
| 815 |
.Ve |
| 816 |
.PP |
| 817 |
\fIIndirect Object Syntax\fR |
| 818 |
.IX Xref "indirect object" |
| 819 |
.IX Subsection "Indirect Object Syntax" |
| 820 |
.PP |
| 821 |
\&\fBOutside of the file handle case, use of this syntax is discouraged as |
| 822 |
it can confuse the Perl interpreter. See below for more details.\fR |
| 823 |
.PP |
| 824 |
Perl supports another method invocation syntax called "indirect object" |
| 825 |
notation. This syntax is called "indirect" because the method comes |
| 826 |
before the object it is being invoked on. |
| 827 |
.PP |
| 828 |
This syntax can be used with any class or object method: |
| 829 |
.PP |
| 830 |
.Vb 2 |
| 831 |
\& my $file = new File $path, $data; |
| 832 |
\& save $file; |
| 833 |
.Ve |
| 834 |
.PP |
| 835 |
We recommend that you avoid this syntax, for several reasons. |
| 836 |
.PP |
| 837 |
First, it can be confusing to read. In the above example, it's not |
| 838 |
clear if \f(CW\*(C`save\*(C'\fR is a method provided by the \f(CW\*(C`File\*(C'\fR class or simply a |
| 839 |
subroutine that expects a file object as its first argument. |
| 840 |
.PP |
| 841 |
When used with class methods, the problem is even worse. Because Perl |
| 842 |
allows subroutine names to be written as barewords, Perl has to guess |
| 843 |
whether the bareword after the method is a class name or subroutine |
| 844 |
name. In other words, Perl can resolve the syntax as either \f(CW\*(C`File\->new( $path, $data )\*(C'\fR \fBor\fR \f(CW\*(C`new( File( $path, $data ) )\*(C'\fR. |
| 845 |
.PP |
| 846 |
To parse this code, Perl uses a heuristic based on what package names |
| 847 |
it has seen, what subroutines exist in the current package, what |
| 848 |
barewords it has previously seen, and other input. Needless to say, |
| 849 |
heuristics can produce very surprising results! |
| 850 |
.PP |
| 851 |
Older documentation (and some CPAN modules) encouraged this syntax, |
| 852 |
particularly for constructors, so you may still find it in the wild. |
| 853 |
However, we encourage you to avoid using it in new code. |
| 854 |
.PP |
| 855 |
You can force Perl to interpret the bareword as a class name by |
| 856 |
appending \f(CW\*(C`::\*(C'\fR to it, like we saw earlier: |
| 857 |
.PP |
| 858 |
.Vb 1 |
| 859 |
\& my $file = new File:: $path, $data; |
| 860 |
.Ve |
| 861 |
.PP |
| 862 |
Indirect object syntax is only available when the |
| 863 |
\&\f(CW"indirect"\fR named feature is enabled. |
| 864 |
This is enabled by default, but can be disabled if requested. This |
| 865 |
feature is present in older feature version bundles, but was removed |
| 866 |
from the \f(CW\*(C`:5.36\*(C'\fR bundle; so a \f(CW\*(C`use VERSION\*(C'\fR |
| 867 |
declaration of \f(CW\*(C`v5.36\*(C'\fR or above will also disable the feature. |
| 868 |
.PP |
| 869 |
.Vb 2 |
| 870 |
\& use v5.36; |
| 871 |
\& # indirect object syntax is no longer available |
| 872 |
.Ve |
| 873 |
.ie n .SS """bless"", ""blessed"", and ""ref""" |
| 874 |
.el .SS "\f(CWbless\fP, \f(CWblessed\fP, and \f(CWref\fP" |
| 875 |
.IX Subsection "bless, blessed, and ref" |
| 876 |
As we saw earlier, an object is simply a data structure that has been |
| 877 |
blessed into a class via the \f(CW\*(C`bless\*(C'\fR function. The \f(CW\*(C`bless\*(C'\fR function |
| 878 |
can take either one or two arguments: |
| 879 |
.PP |
| 880 |
.Vb 2 |
| 881 |
\& my $object = bless {}, $class; |
| 882 |
\& my $object = bless {}; |
| 883 |
.Ve |
| 884 |
.PP |
| 885 |
In the first form, the anonymous hash is being blessed into the class |
| 886 |
in \f(CW$class\fR. In the second form, the anonymous hash is blessed into |
| 887 |
the current package. |
| 888 |
.PP |
| 889 |
The second form is strongly discouraged, because it breaks the ability |
| 890 |
of a subclass to reuse the parent's constructor, but you may still run |
| 891 |
across it in existing code. |
| 892 |
.PP |
| 893 |
If you want to know whether a particular scalar refers to an object, |
| 894 |
you can use the \f(CW\*(C`blessed\*(C'\fR function exported by Scalar::Util, which |
| 895 |
is shipped with the Perl core. |
| 896 |
.PP |
| 897 |
.Vb 1 |
| 898 |
\& use Scalar::Util \*(Aqblessed\*(Aq; |
| 899 |
\& |
| 900 |
\& if ( defined blessed($thing) ) { ... } |
| 901 |
.Ve |
| 902 |
.PP |
| 903 |
If \f(CW$thing\fR refers to an object, then this function returns the name |
| 904 |
of the package the object has been blessed into. If \f(CW$thing\fR doesn't |
| 905 |
contain a reference to a blessed object, the \f(CW\*(C`blessed\*(C'\fR function |
| 906 |
returns \f(CW\*(C`undef\*(C'\fR. |
| 907 |
.PP |
| 908 |
Note that \f(CWblessed($thing)\fR will also return false if \f(CW$thing\fR has |
| 909 |
been blessed into a class named "0". This is a possible, but quite |
| 910 |
pathological. Don't create a class named "0" unless you know what |
| 911 |
you're doing. |
| 912 |
.PP |
| 913 |
Similarly, Perl's built-in \f(CW\*(C`ref\*(C'\fR function treats a reference to a |
| 914 |
blessed object specially. If you call \f(CWref($thing)\fR and \f(CW$thing\fR |
| 915 |
holds a reference to an object, it will return the name of the class |
| 916 |
that the object has been blessed into. |
| 917 |
.PP |
| 918 |
If you simply want to check that a variable contains an object |
| 919 |
reference, we recommend that you use \f(CW\*(C`defined blessed($object)\*(C'\fR, since |
| 920 |
\&\f(CW\*(C`ref\*(C'\fR returns true values for all references, not just objects. |
| 921 |
.SS "The UNIVERSAL Class" |
| 922 |
.IX Xref "UNIVERSAL" |
| 923 |
.IX Subsection "The UNIVERSAL Class" |
| 924 |
All classes automatically inherit from the UNIVERSAL class, which is |
| 925 |
built-in to the Perl core. This class provides a number of methods, all |
| 926 |
of which can be called on either a class or an object. You can also |
| 927 |
choose to override some of these methods in your class. If you do so, |
| 928 |
we recommend that you follow the built-in semantics described below. |
| 929 |
.IP isa($class) 4 |
| 930 |
.IX Xref "isa" |
| 931 |
.IX Item "isa($class)" |
| 932 |
The \f(CW\*(C`isa\*(C'\fR method returns \fItrue\fR if the object is a member of the |
| 933 |
class in \f(CW$class\fR, or a member of a subclass of \f(CW$class\fR. |
| 934 |
.Sp |
| 935 |
If you override this method, it should never throw an exception. |
| 936 |
.IP DOES($role) 4 |
| 937 |
.IX Xref "DOES" |
| 938 |
.IX Item "DOES($role)" |
| 939 |
The \f(CW\*(C`DOES\*(C'\fR method returns \fItrue\fR if its object claims to perform the |
| 940 |
role \f(CW$role\fR. By default, this is equivalent to \f(CW\*(C`isa\*(C'\fR. This method is |
| 941 |
provided for use by object system extensions that implement roles, like |
| 942 |
\&\f(CW\*(C`Moose\*(C'\fR and \f(CW\*(C`Role::Tiny\*(C'\fR. |
| 943 |
.Sp |
| 944 |
You can also override \f(CW\*(C`DOES\*(C'\fR directly in your own classes. If you |
| 945 |
override this method, it should never throw an exception. |
| 946 |
.IP can($method) 4 |
| 947 |
.IX Xref "can" |
| 948 |
.IX Item "can($method)" |
| 949 |
The \f(CW\*(C`can\*(C'\fR method checks to see if the class or object it was called on |
| 950 |
has a method named \f(CW$method\fR. This checks for the method in the class |
| 951 |
and all of its parents. If the method exists, then a reference to the |
| 952 |
subroutine is returned. If it does not then \f(CW\*(C`undef\*(C'\fR is returned. |
| 953 |
.Sp |
| 954 |
If your class responds to method calls via \f(CW\*(C`AUTOLOAD\*(C'\fR, you may want to |
| 955 |
overload \f(CW\*(C`can\*(C'\fR to return a subroutine reference for methods which your |
| 956 |
\&\f(CW\*(C`AUTOLOAD\*(C'\fR method handles. |
| 957 |
.Sp |
| 958 |
If you override this method, it should never throw an exception. |
| 959 |
.IP VERSION($need) 4 |
| 960 |
.IX Xref "VERSION" |
| 961 |
.IX Item "VERSION($need)" |
| 962 |
The \f(CW\*(C`VERSION\*(C'\fR method returns the version number of the class |
| 963 |
(package). |
| 964 |
.Sp |
| 965 |
If the \f(CW$need\fR argument is given then it will check that the current |
| 966 |
version (as defined by the \f(CW$VERSION\fR variable in the package) is greater |
| 967 |
than or equal to \f(CW$need\fR; it will die if this is not the case. This |
| 968 |
method is called automatically by the \f(CW\*(C`VERSION\*(C'\fR form of \f(CW\*(C`use\*(C'\fR. |
| 969 |
.Sp |
| 970 |
.Vb 3 |
| 971 |
\& use Package 1.2 qw(some imported subs); |
| 972 |
\& # implies: |
| 973 |
\& Package\->VERSION(1.2); |
| 974 |
.Ve |
| 975 |
.Sp |
| 976 |
We recommend that you use this method to access another package's |
| 977 |
version, rather than looking directly at \f(CW$Package::VERSION\fR. The |
| 978 |
package you are looking at could have overridden the \f(CW\*(C`VERSION\*(C'\fR method. |
| 979 |
.Sp |
| 980 |
We also recommend using this method to check whether a module has a |
| 981 |
sufficient version. The internal implementation uses the version |
| 982 |
module to make sure that different types of version numbers are |
| 983 |
compared correctly. |
| 984 |
.SS AUTOLOAD |
| 985 |
.IX Xref "AUTOLOAD" |
| 986 |
.IX Subsection "AUTOLOAD" |
| 987 |
If you call a method that doesn't exist in a class, Perl will throw an |
| 988 |
error. However, if that class or any of its parent classes defines an |
| 989 |
\&\f(CW\*(C`AUTOLOAD\*(C'\fR method, that \f(CW\*(C`AUTOLOAD\*(C'\fR method is called instead. |
| 990 |
.PP |
| 991 |
\&\f(CW\*(C`AUTOLOAD\*(C'\fR is called as a regular method, and the caller will not know |
| 992 |
the difference. Whatever value your \f(CW\*(C`AUTOLOAD\*(C'\fR method returns is |
| 993 |
returned to the caller. |
| 994 |
.PP |
| 995 |
The fully qualified method name that was called is available in the |
| 996 |
\&\f(CW$AUTOLOAD\fR package global for your class. Since this is a global, if |
| 997 |
you want to refer to do it without a package name prefix under \f(CWstrict |
| 998 |
\&\*(Aqvars\*(Aq\fR, you need to declare it. |
| 999 |
.PP |
| 1000 |
.Vb 5 |
| 1001 |
\& # XXX \- this is a terrible way to implement accessors, but it makes |
| 1002 |
\& # for a simple example. |
| 1003 |
\& our $AUTOLOAD; |
| 1004 |
\& sub AUTOLOAD { |
| 1005 |
\& my $self = shift; |
| 1006 |
\& |
| 1007 |
\& # Remove qualifier from original method name... |
| 1008 |
\& my $called = $AUTOLOAD =~ s/.*:://r; |
| 1009 |
\& |
| 1010 |
\& # Is there an attribute of that name? |
| 1011 |
\& die "No such attribute: $called" |
| 1012 |
\& unless exists $self\->{$called}; |
| 1013 |
\& |
| 1014 |
\& # If so, return it... |
| 1015 |
\& return $self\->{$called}; |
| 1016 |
\& } |
| 1017 |
\& |
| 1018 |
\& sub DESTROY { } # see below |
| 1019 |
.Ve |
| 1020 |
.PP |
| 1021 |
Without the \f(CW\*(C`our $AUTOLOAD\*(C'\fR declaration, this code will not compile |
| 1022 |
under the strict pragma. |
| 1023 |
.PP |
| 1024 |
As the comment says, this is not a good way to implement accessors. |
| 1025 |
It's slow and too clever by far. However, you may see this as a way to |
| 1026 |
provide accessors in older Perl code. See perlootut for |
| 1027 |
recommendations on OO coding in Perl. |
| 1028 |
.PP |
| 1029 |
If your class does have an \f(CW\*(C`AUTOLOAD\*(C'\fR method, we strongly recommend |
| 1030 |
that you override \f(CW\*(C`can\*(C'\fR in your class as well. Your overridden \f(CW\*(C`can\*(C'\fR |
| 1031 |
method should return a subroutine reference for any method that your |
| 1032 |
\&\f(CW\*(C`AUTOLOAD\*(C'\fR responds to. |
| 1033 |
.SS Destructors |
| 1034 |
.IX Xref "destructor DESTROY" |
| 1035 |
.IX Subsection "Destructors" |
| 1036 |
When the last reference to an object goes away, the object is |
| 1037 |
destroyed. If you only have one reference to an object stored in a |
| 1038 |
lexical scalar, the object is destroyed when that scalar goes out of |
| 1039 |
scope. If you store the object in a package global, that object may not |
| 1040 |
go out of scope until the program exits. |
| 1041 |
.PP |
| 1042 |
If you want to do something when the object is destroyed, you can |
| 1043 |
define a \f(CW\*(C`DESTROY\*(C'\fR method in your class. This method will always be |
| 1044 |
called by Perl at the appropriate time, unless the method is empty. |
| 1045 |
.PP |
| 1046 |
This is called just like any other method, with the object as the first |
| 1047 |
argument. It does not receive any additional arguments. However, the |
| 1048 |
\&\f(CW$_[0]\fR variable will be read-only in the destructor, so you cannot |
| 1049 |
assign a value to it. |
| 1050 |
.PP |
| 1051 |
If your \f(CW\*(C`DESTROY\*(C'\fR method throws an exception, this will not cause |
| 1052 |
any control transfer beyond exiting the method. The exception will be |
| 1053 |
reported to \f(CW\*(C`STDERR\*(C'\fR as a warning, marked "(in cleanup)", and Perl will |
| 1054 |
continue with whatever it was doing before. |
| 1055 |
.PP |
| 1056 |
Because \f(CW\*(C`DESTROY\*(C'\fR methods can be called at any time, you should localize |
| 1057 |
any global status variables that might be set by anything you do in |
| 1058 |
your \f(CW\*(C`DESTROY\*(C'\fR method. If you are in doubt about a particular status |
| 1059 |
variable, it doesn't hurt to localize it. There are five global status |
| 1060 |
variables, and the safest way is to localize all five of them: |
| 1061 |
.PP |
| 1062 |
.Vb 5 |
| 1063 |
\& sub DESTROY { |
| 1064 |
\& local($., $@, $!, $^E, $?); |
| 1065 |
\& my $self = shift; |
| 1066 |
\& ...; |
| 1067 |
\& } |
| 1068 |
.Ve |
| 1069 |
.PP |
| 1070 |
If you define an \f(CW\*(C`AUTOLOAD\*(C'\fR in your class, then Perl will call your |
| 1071 |
\&\f(CW\*(C`AUTOLOAD\*(C'\fR to handle the \f(CW\*(C`DESTROY\*(C'\fR method. You can prevent this by |
| 1072 |
defining an empty \f(CW\*(C`DESTROY\*(C'\fR, like we did in the autoloading example. |
| 1073 |
You can also check the value of \f(CW$AUTOLOAD\fR and return without doing |
| 1074 |
anything when called to handle \f(CW\*(C`DESTROY\*(C'\fR. |
| 1075 |
.PP |
| 1076 |
\fIGlobal Destruction\fR |
| 1077 |
.IX Subsection "Global Destruction" |
| 1078 |
.PP |
| 1079 |
The order in which objects are destroyed during the global destruction |
| 1080 |
before the program exits is unpredictable. This means that any objects |
| 1081 |
contained by your object may already have been destroyed. You should |
| 1082 |
check that a contained object is defined before calling a method on it: |
| 1083 |
.PP |
| 1084 |
.Vb 2 |
| 1085 |
\& sub DESTROY { |
| 1086 |
\& my $self = shift; |
| 1087 |
\& |
| 1088 |
\& $self\->{handle}\->close() if $self\->{handle}; |
| 1089 |
\& } |
| 1090 |
.Ve |
| 1091 |
.PP |
| 1092 |
You can use the \f(CW\*(C`${^GLOBAL_PHASE}\*(C'\fR variable to detect if you are |
| 1093 |
currently in the global destruction phase: |
| 1094 |
.PP |
| 1095 |
.Vb 2 |
| 1096 |
\& sub DESTROY { |
| 1097 |
\& my $self = shift; |
| 1098 |
\& |
| 1099 |
\& return if ${^GLOBAL_PHASE} eq \*(AqDESTRUCT\*(Aq; |
| 1100 |
\& |
| 1101 |
\& $self\->{handle}\->close(); |
| 1102 |
\& } |
| 1103 |
.Ve |
| 1104 |
.PP |
| 1105 |
Note that this variable was added in Perl 5.14.0. If you want to detect |
| 1106 |
the global destruction phase on older versions of Perl, you can use the |
| 1107 |
\&\f(CW\*(C`Devel::GlobalDestruction\*(C'\fR module on CPAN. |
| 1108 |
.PP |
| 1109 |
If your \f(CW\*(C`DESTROY\*(C'\fR method issues a warning during global destruction, |
| 1110 |
the Perl interpreter will append the string " during global |
| 1111 |
destruction" to the warning. |
| 1112 |
.PP |
| 1113 |
During global destruction, Perl will always garbage collect objects |
| 1114 |
before unblessed references. See "PERL_DESTRUCT_LEVEL" in perlhacktips |
| 1115 |
for more information about global destruction. |
| 1116 |
.SS "Non-Hash Objects" |
| 1117 |
.IX Subsection "Non-Hash Objects" |
| 1118 |
All the examples so far have shown objects based on a blessed hash. |
| 1119 |
However, it's possible to bless any type of data structure or referent, |
| 1120 |
including scalars, globs, and subroutines. You may see this sort of |
| 1121 |
thing when looking at code in the wild. |
| 1122 |
.PP |
| 1123 |
Here's an example of a module as a blessed scalar: |
| 1124 |
.PP |
| 1125 |
.Vb 1 |
| 1126 |
\& package Time; |
| 1127 |
\& |
| 1128 |
\& use v5.36; |
| 1129 |
\& |
| 1130 |
\& sub new { |
| 1131 |
\& my $class = shift; |
| 1132 |
\& |
| 1133 |
\& my $time = time; |
| 1134 |
\& return bless \e$time, $class; |
| 1135 |
\& } |
| 1136 |
\& |
| 1137 |
\& sub epoch { |
| 1138 |
\& my $self = shift; |
| 1139 |
\& return $$self; |
| 1140 |
\& } |
| 1141 |
\& |
| 1142 |
\& my $time = Time\->new(); |
| 1143 |
\& print $time\->epoch(); |
| 1144 |
.Ve |
| 1145 |
.SS "Inside-Out objects" |
| 1146 |
.IX Subsection "Inside-Out objects" |
| 1147 |
In the past, the Perl community experimented with a technique called |
| 1148 |
"inside-out objects". An inside-out object stores its data outside of |
| 1149 |
the object's reference, indexed on a unique property of the object, |
| 1150 |
such as its memory address, rather than in the object itself. This has |
| 1151 |
the advantage of enforcing the encapsulation of object attributes, |
| 1152 |
since their data is not stored in the object itself. |
| 1153 |
.PP |
| 1154 |
This technique was popular for a while (and was recommended in Damian |
| 1155 |
Conway's \fIPerl Best Practices\fR), but never achieved universal |
| 1156 |
adoption. The Object::InsideOut module on CPAN provides a |
| 1157 |
comprehensive implementation of this technique, and you may see it or |
| 1158 |
other inside-out modules in the wild. |
| 1159 |
.PP |
| 1160 |
Here is a simple example of the technique, using the |
| 1161 |
Hash::Util::FieldHash core module. This module was added to the core |
| 1162 |
to support inside-out object implementations. |
| 1163 |
.PP |
| 1164 |
.Vb 1 |
| 1165 |
\& package Time; |
| 1166 |
\& |
| 1167 |
\& use v5.36; |
| 1168 |
\& |
| 1169 |
\& use Hash::Util::FieldHash \*(Aqfieldhash\*(Aq; |
| 1170 |
\& |
| 1171 |
\& fieldhash my %time_for; |
| 1172 |
\& |
| 1173 |
\& sub new { |
| 1174 |
\& my $class = shift; |
| 1175 |
\& |
| 1176 |
\& my $self = bless \e( my $object ), $class; |
| 1177 |
\& |
| 1178 |
\& $time_for{$self} = time; |
| 1179 |
\& |
| 1180 |
\& return $self; |
| 1181 |
\& } |
| 1182 |
\& |
| 1183 |
\& sub epoch { |
| 1184 |
\& my $self = shift; |
| 1185 |
\& |
| 1186 |
\& return $time_for{$self}; |
| 1187 |
\& } |
| 1188 |
\& |
| 1189 |
\& my $time = Time\->new; |
| 1190 |
\& print $time\->epoch; |
| 1191 |
.Ve |
| 1192 |
.SS Pseudo-hashes |
| 1193 |
.IX Subsection "Pseudo-hashes" |
| 1194 |
The pseudo-hash feature was an experimental feature introduced in |
| 1195 |
earlier versions of Perl and removed in 5.10.0. A pseudo-hash is an |
| 1196 |
array reference which can be accessed using named keys like a hash. You |
| 1197 |
may run in to some code in the wild which uses it. See the fields |
| 1198 |
pragma for more information. |
| 1199 |
.SH "SEE ALSO" |
| 1200 |
.IX Header "SEE ALSO" |
| 1201 |
A kinder, gentler tutorial on object-oriented programming in Perl can |
| 1202 |
be found in perlootut. You should also check out perlmodlib for |
| 1203 |
some style guides on constructing both modules and classes. |