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