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 | ||
af36000c DR |
328 | say 'A'; |
329 | } | |
330 | ||
331 | package B; | |
332 | ||
77d38c8d | 333 | use parent -norequire, 'A'; |
af36000c DR |
334 | |
335 | sub speak { | |
336 | my $self = shift; | |
029f3b44 | 337 | |
af36000c | 338 | $self->SUPER::speak(); |
a0d0e21e | 339 | |
af36000c DR |
340 | say 'B'; |
341 | } | |
a0d0e21e | 342 | |
af36000c | 343 | package C; |
cb1a09d0 | 344 | |
77d38c8d | 345 | use parent -norequire, 'B'; |
cb1a09d0 | 346 | |
af36000c DR |
347 | sub speak { |
348 | my $self = shift; | |
d9693f5a | 349 | |
af36000c | 350 | $self->SUPER::speak(); |
e947c198 | 351 | |
af36000c DR |
352 | say 'C'; |
353 | } | |
e947c198 | 354 | |
af36000c DR |
355 | my $c = C->new(); |
356 | $c->speak(); | |
e947c198 | 357 | |
7168b251 | 358 | In this example, we will get the following output: |
cb1a09d0 | 359 | |
af36000c DR |
360 | A |
361 | B | |
362 | C | |
748a9306 | 363 | |
af36000c DR |
364 | This demonstrates how C<SUPER> is resolved. Even though the object is |
365 | blessed into the C<C> class, the C<speak()> method in the C<B> class | |
7168b251 DC |
366 | can still call C<SUPER::speak()> and expect it to correctly look in the |
367 | parent class of C<B> (i.e the class the method call is in), not in the | |
368 | parent class of C<C> (i.e. the class the object belongs to). | |
19799a22 | 369 | |
7168b251 DC |
370 | There are rare cases where this package-based resolution can be a |
371 | problem. If you copy a subroutine from one package to another, C<SUPER> | |
af36000c | 372 | resolution will be done based on the original package. |
19799a22 | 373 | |
af36000c DR |
374 | =head3 Multiple Inheritance |
375 | X<multiple inheritance> | |
19799a22 | 376 | |
af36000c | 377 | Multiple inheritance often indicates a design problem, but Perl always |
2898ff73 | 378 | gives you enough rope to hang yourself with if you ask for it. |
19799a22 | 379 | |
af36000c DR |
380 | To declare multiple parents, you simply need to pass multiple class |
381 | names to C<use parent>: | |
5d9f8747 | 382 | |
af36000c | 383 | package MultiChild; |
5d9f8747 | 384 | |
af36000c | 385 | use parent 'Parent1', 'Parent2'; |
19799a22 | 386 | |
af36000c DR |
387 | =head3 Method Resolution Order |
388 | X<method resolution order> X<mro> | |
389 | ||
390 | Method resolution order only matters in the case of multiple | |
391 | inheritance. In the case of single inheritance, Perl simply looks up | |
392 | the inheritance chain to find a method: | |
393 | ||
394 | Grandparent | |
7168b251 | 395 | | |
af36000c | 396 | Parent |
7168b251 | 397 | | |
af36000c DR |
398 | Child |
399 | ||
400 | If we call a method on a C<Child> object and that method is not defined | |
7168b251 DC |
401 | in the C<Child> class, Perl will look for that method in the C<Parent> |
402 | class and then, if necessary, in the C<Grandparent> class. | |
af36000c DR |
403 | |
404 | If Perl cannot find the method in any of these classes, it will die | |
405 | with an error message. | |
406 | ||
407 | When a class has multiple parents, the method lookup order becomes more | |
408 | complicated. | |
409 | ||
410 | By default, Perl does a depth-first left-to-right search for a method. | |
411 | That means it starts with the first parent in the C<@ISA> array, and | |
7168b251 DC |
412 | then searches all of its parents, grandparents, etc. If it fails to |
413 | find the method, it then goes to the next parent in the original | |
414 | class's C<@ISA> array and searches from there. | |
af36000c | 415 | |
7168b251 DC |
416 | SharedGreatGrandParent |
417 | / \ | |
af36000c DR |
418 | PaternalGrandparent MaternalGrandparent |
419 | \ / | |
420 | Father Mother | |
421 | \ / | |
422 | Child | |
423 | ||
424 | So given the diagram above, Perl will search C<Child>, C<Father>, | |
7168b251 | 425 | C<PaternalGrandparent>, C<SharedGreatGrandParent>, C<Mother>, and |
2898ff73 | 426 | finally C<MaternalGrandparent>. This may be a problem because now we're |
7168b251 DC |
427 | looking in C<SharedGreatGrandParent> I<before> we've checked all its |
428 | derived classes (i.e. before we tried C<Mother> and | |
429 | C<MaternalGrandparent>). | |
af36000c DR |
430 | |
431 | It is possible to ask for a different method resolution order with the | |
432 | L<mro> pragma. | |
433 | ||
434 | package Child; | |
435 | ||
436 | use mro 'c3'; | |
437 | use parent 'Father', 'Mother'; | |
438 | ||
439 | This pragma lets you switch to the "C3" resolution order. In simple | |
2898ff73 DR |
440 | terms, "C3" order ensures that shared parent classes are never searched |
441 | before child classes, so Perl will now search: C<Child>, C<Father>, | |
7168b251 DC |
442 | C<PaternalGrandparent>, C<Mother> C<MaternalGrandparent>, and finally |
443 | C<SharedGreatGrandParent>. Note however that this is not | |
444 | "breadth-first" searching: All the C<Father> ancestors (except the | |
445 | common ancestor) are searched before any of the C<Mother> ancestors are | |
446 | considered. | |
af36000c DR |
447 | |
448 | The C3 order also lets you call methods in sibling classes with the | |
449 | C<next> pseudo-class. See the L<mro> documentation for more details on | |
450 | this feature. | |
451 | ||
452 | =head3 Method Resolution Caching | |
453 | ||
454 | When Perl searches for a method, it caches the lookup so that future | |
455 | calls to the method do not need to search for it again. Changing a | |
456 | class's parent class or adding subroutines to a class will invalidate | |
457 | the cache for that class. | |
458 | ||
459 | The L<mro> pragma provides some functions for manipulating the method | |
460 | cache directly. | |
461 | ||
462 | =head2 Writing Constructors | |
463 | X<constructor> | |
464 | ||
465 | As we mentioned earlier, Perl provides no special constructor syntax. | |
466 | This means that a class must implement its own constructor. A | |
7168b251 DC |
467 | constructor is simply a class method that returns a reference to a new |
468 | object. | |
af36000c DR |
469 | |
470 | The constructor can also accept additional parameters that define the | |
471 | object. Let's write a real constructor for the C<File> class we used | |
472 | earlier: | |
473 | ||
474 | package File; | |
475 | ||
476 | sub new { | |
477 | my $class = shift; | |
478 | my ( $path, $data ) = @_; | |
479 | ||
480 | my $self = bless { | |
481 | path => $path, | |
482 | data => $data, | |
483 | }, $class; | |
484 | ||
485 | return $self; | |
486 | } | |
487 | ||
488 | As you can see, we've stored the path and file data in the object | |
7168b251 DC |
489 | itself. Remember, under the hood, this object is still just a hash. |
490 | Later, we'll write accessors to manipulate this data. | |
af36000c DR |
491 | |
492 | For our File::MP3 class, we can check to make sure that the path we're | |
493 | given ends with ".mp3": | |
494 | ||
495 | package File::MP3; | |
496 | ||
497 | sub new { | |
498 | my $class = shift; | |
499 | my ( $path, $data ) = @_; | |
500 | ||
501 | die "You cannot create a File::MP3 without an mp3 extension\n" | |
502 | unless $path =~ /\.mp3\z/; | |
503 | ||
504 | return $class->SUPER::new(@_); | |
505 | } | |
506 | ||
507 | This constructor lets its parent class do the actual object | |
508 | construction. | |
509 | ||
8d26c1a8 DR |
510 | =head2 Attributes |
511 | X<attribute> | |
512 | ||
513 | An attribute is a piece of data belonging to a particular object. | |
514 | Unlike most object-oriented languages, Perl provides no special syntax | |
515 | or support for declaring and manipulating attributes. | |
516 | ||
517 | Attributes are often stored in the object itself. For example, if the | |
7168b251 DC |
518 | object is an anonymous hash, we can store the attribute values in the |
519 | hash using the attribute name as the key. | |
8d26c1a8 DR |
520 | |
521 | While it's possible to refer directly to these hash keys outside of the | |
522 | class, it's considered a best practice to wrap all access to the | |
523 | attribute with accessor methods. | |
524 | ||
7168b251 | 525 | This has several advantages. Accessors make it easier to change the |
8d26c1a8 DR |
526 | implementation of an object later while still preserving the original |
527 | API. | |
528 | ||
529 | An accessor lets you add additional code around attribute access. For | |
530 | example, you could apply a default to an attribute that wasn't set in | |
531 | the constructor, or you could validate that a new value for the | |
532 | attribute is acceptable. | |
533 | ||
534 | Finally, using accessors makes inheritance much simpler. Subclasses can | |
2898ff73 DR |
535 | use the accessors rather than having to know how a parent class is |
536 | implemented internally. | |
8d26c1a8 DR |
537 | |
538 | =head3 Writing Accessors | |
af36000c DR |
539 | X<accessor> |
540 | ||
541 | As with constructors, Perl provides no special accessor declaration | |
2898ff73 DR |
542 | syntax, so classes must provide explicitly written accessor methods. |
543 | There are two common types of accessors, read-only and read-write. | |
af36000c DR |
544 | |
545 | A simple read-only accessor simply gets the value of a single | |
546 | attribute: | |
547 | ||
548 | sub path { | |
549 | my $self = shift; | |
550 | ||
551 | return $self->{path}; | |
552 | } | |
553 | ||
554 | A read-write accessor will allow the caller to set the value as well as | |
555 | get it: | |
556 | ||
557 | sub path { | |
558 | my $self = shift; | |
559 | ||
560 | if (@_) { | |
561 | $self->{path} = shift; | |
562 | } | |
563 | ||
564 | return $self->{path}; | |
565 | } | |
566 | ||
567 | =head2 An Aside About Smarter and Safer Code | |
568 | ||
569 | Our constructor and accessors are not very smart. They don't check that | |
570 | a C<$path> is defined, nor do they check that a C<$path> is a valid | |
571 | filesystem path. | |
572 | ||
573 | Doing these checks by hand can quickly become tedious. Writing a bunch | |
8d26c1a8 | 574 | of accessors by hand is also incredibly tedious. There are a lot of |
af36000c DR |
575 | modules on CPAN that can help you write safer and more concise code, |
576 | including the modules we recommend in L<perlootut>. | |
577 | ||
578 | =head2 Method Call Variations | |
579 | X<method> | |
19799a22 | 580 | |
2898ff73 DR |
581 | Perl supports several other ways to call methods besides the C<< |
582 | $object->method() >> usage we've seen so far. | |
19799a22 | 583 | |
af36000c | 584 | =head3 Method Names as Strings |
19799a22 | 585 | |
af36000c DR |
586 | Perl lets you use a scalar variable containing a string as a method |
587 | name: | |
19799a22 | 588 | |
af36000c | 589 | my $file = File->new( $path, $data ); |
19799a22 | 590 | |
af36000c DR |
591 | my $method = 'save'; |
592 | $file->$method(); | |
19799a22 | 593 | |
af36000c DR |
594 | This works exactly like calling C<< $file->save() >>. This can be very |
595 | useful for writing dynamic code. For example, it allows you to pass a | |
596 | method name to be called as a parameter to another method. | |
5d9f8747 | 597 | |
af36000c | 598 | =head3 Class Names as Strings |
748a9306 | 599 | |
af36000c DR |
600 | Perl also lets you use a scalar containing a string as a class name: |
601 | ||
602 | my $class = 'File'; | |
603 | ||
604 | my $file = $class->new( $path, $data ); | |
605 | ||
606 | Again, this allows for very dynamic code. | |
607 | ||
608 | =head3 Subroutine References as Methods | |
609 | ||
7168b251 | 610 | You can also use a subroutine reference as a method: |
af36000c DR |
611 | |
612 | my $sub = sub { | |
613 | my $self = shift; | |
614 | ||
615 | $self->save(); | |
616 | }; | |
617 | ||
618 | $file->$sub(); | |
619 | ||
620 | This is exactly equivalent to writing C<< $sub->($file) >>. You may see | |
621 | this idiom in the wild combined with a call to C<can>: | |
622 | ||
623 | if ( my $meth = $object->can('foo') ) { | |
624 | $object->$meth(); | |
625 | } | |
626 | ||
8d26c1a8 DR |
627 | =head3 Deferencing Method Call |
628 | ||
629 | Perl also lets you use a dereferenced scalar reference in a method | |
630 | call. That's a mouthful, so let's look at some code: | |
631 | ||
632 | $file->${ \'save' }; | |
633 | $file->${ returns_scalar_ref() }; | |
634 | $file->${ \( returns_scalar() ) }; | |
2898ff73 | 635 | $file->${ returns_sub_ref() }; |
8d26c1a8 DR |
636 | |
637 | This works if the dereference produces a string I<or> a subroutine | |
638 | reference. | |
639 | ||
640 | =head3 Method Calls on Filehandles | |
641 | ||
642 | Under the hood, Perl filehandles are instances of the C<IO::Handle> or | |
643 | C<IO::File> class. Once you have an open filehandle, you can call | |
7168b251 | 644 | methods on it. Additionally, you can call methods on the C<STDIN>, |
8d26c1a8 DR |
645 | C<STDOUT>, and C<STDERR> filehandles. |
646 | ||
647 | open my $fh, '>', 'path/to/file'; | |
648 | $fh->autoflush(); | |
649 | $fh->print('content'); | |
650 | ||
651 | STDOUT->autoflush(); | |
652 | ||
af36000c DR |
653 | =head2 Invoking Class Methods |
654 | X<invocation> | |
655 | ||
656 | Because Perl allows you to use barewords for package names and | |
2898ff73 DR |
657 | subroutine names, it sometimes interprets a bareword's meaning |
658 | incorrectly. For example, the construct C<< Class->new() >> can be | |
7168b251 DC |
659 | interpreted as either C<< 'Class'->new() >> or C<< Class()->new() >>. |
660 | In English, that second interpretation reads as "call a subroutine | |
2898ff73 DR |
661 | named Class(), then call new() as a method on the return value of |
662 | Class()". If there is a subroutine named C<Class()> in the current | |
663 | namespace, Perl will always interpret C<< Class->new() >> as the second | |
664 | alternative: a call to C<new()> on the object returned by a call to | |
665 | C<Class()> | |
7168b251 DC |
666 | |
667 | You can force Perl to use the first interpretation (i.e. as a method | |
668 | call on the class named "Class") in two ways. First, you can append a | |
669 | C<::> to the class name: | |
af36000c DR |
670 | |
671 | Class::->new() | |
672 | ||
7168b251 DC |
673 | Perl will always interpret this as a method call. |
674 | ||
675 | Alternatively, you can quote the class name: | |
af36000c DR |
676 | |
677 | 'Class'->new() | |
678 | ||
679 | Of course, if the class name is in a scalar Perl will do the right | |
680 | thing as well: | |
681 | ||
682 | my $class = 'Class'; | |
683 | $class->new(); | |
684 | ||
685 | =head3 Indirect Object Syntax | |
686 | X<indirect object> | |
687 | ||
688 | B<Outside of the file handle case, use of this syntax is discouraged, | |
689 | as it can confuse the Perl interpreter. See below for more details.> | |
690 | ||
691 | Perl suports another method invocation syntax called "indirect object" | |
8d26c1a8 DR |
692 | notation. This syntax is called "indirect" because the method comes |
693 | before the object it is being invoked on. | |
af36000c DR |
694 | |
695 | This syntax can be used with any class or object method: | |
696 | ||
697 | my $file = new File $path, $data; | |
698 | save $file; | |
699 | ||
700 | We recommend that you avoid this syntax, for several reasons. | |
701 | ||
702 | First, it can be confusing to read. In the above example, it's not | |
2898ff73 DR |
703 | clear if C<save> is a method provided by the C<File> class or simply a |
704 | subroutine that expects a file object as its first argument. | |
af36000c DR |
705 | |
706 | When used with class methods, the problem is even worse. Because Perl | |
707 | allows subroutine names to be written as barewords, Perl has to guess | |
708 | whether the bareword after the method is a class name or subroutine | |
709 | name. In other words, Perl can resolve the syntax as either C<< | |
710 | File->new( $path, $data ) >> B<or> C<< new( File( $path, $data ) ) >>. | |
711 | ||
712 | To parse this code, Perl uses a heuristic based on what package names | |
8d26c1a8 DR |
713 | it has seen, what subroutines exist in the current package, what |
714 | barewords it has previously seen, and other input. Needless to say, | |
715 | heuristics can produce very surprising results! | |
af36000c DR |
716 | |
717 | Older documentation (and some CPAN modules) encouraged this syntax, | |
718 | particularly for constructors, so you may still find it in the wild. | |
719 | However, we encourage you to avoid using it in new code. | |
720 | ||
8d26c1a8 DR |
721 | You can force Perl to interpret the bareword as a class name by |
722 | appending "::" to it, like we saw earlier: | |
723 | ||
724 | my $file = new File:: $path, $data; | |
725 | ||
af36000c DR |
726 | =head2 C<bless>, C<blessed>, and C<ref> |
727 | ||
7168b251 DC |
728 | As we saw earlier, an object is simply a data structure that has been |
729 | blessed into a class via the C<bless> function. The C<bless> function | |
8d26c1a8 | 730 | can take either one or two arguments: |
af36000c DR |
731 | |
732 | my $object = bless {}, $class; | |
733 | my $object = bless {}; | |
734 | ||
7168b251 DC |
735 | In the first form, the anonymous hash is being blessed into the class |
736 | in C<$class>. In the second form, the anonymous hash is blessed into | |
737 | the current package. | |
af36000c | 738 | |
7168b251 DC |
739 | The second form is strongly discouraged, because it breaks the ability |
740 | of a subclass to reuse the parent's constructor, but you may still run | |
af36000c DR |
741 | across it in existing code. |
742 | ||
8d26c1a8 DR |
743 | If you want to know whether a particular scalar refers to an object, |
744 | you can use the C<blessed> function exported by L<Scalar::Util>, which | |
745 | is shipped with the Perl core. | |
af36000c DR |
746 | |
747 | use Scalar::Util 'blessed'; | |
748 | ||
2898ff73 | 749 | if ( defined blessed($thing) ) { ... } |
af36000c | 750 | |
7168b251 | 751 | If C<$thing> refers to an object, then this function returns the name |
2898ff73 DR |
752 | of the package the object has been blessed into. If C<$thing> doesn't |
753 | contain a reference to a blessed object, the C<blessed> function | |
754 | returns C<undef>. | |
755 | ||
756 | Note that C<blessed($thing)> will also return false if C<$thing> has | |
757 | been blessed into a class named "0". This is a possible, but quite | |
758 | pathological. Don't create a class named "0" unless you know what | |
759 | you're doing. | |
af36000c | 760 | |
7168b251 DC |
761 | Similarly, Perl's built-in C<ref> function treats a reference to a |
762 | blessed object specially. If you call C<ref($thing)> and C<$thing> | |
763 | holds a reference to an object, it will return the name of the class | |
764 | that the object has been blessed into. | |
af36000c | 765 | |
7168b251 DC |
766 | If you simply want to check that a variable contains an object |
767 | reference, we recommend that you use C<defined blessed($object)>, since | |
768 | C<ref> returns true values for all references, not just objects. | |
af36000c DR |
769 | |
770 | =head2 The UNIVERSAL Class | |
d74e8afc | 771 | X<UNIVERSAL> |
a2bdc9a5 | 772 | |
af36000c | 773 | All classes automatically inherit from the L<UNIVERSAL> class, which is |
8d26c1a8 | 774 | built-in to the Perl core. This class provides a number of methods, all |
af36000c DR |
775 | of which can be called on either a class or an object. You can also |
776 | choose to override some of these methods in your class. If you do so, | |
8d26c1a8 | 777 | we recommend that you follow the built-in semantics described below. |
a2bdc9a5 | 778 | |
779 | =over 4 | |
780 | ||
af36000c | 781 | =item isa($class) |
d74e8afc | 782 | X<isa> |
a2bdc9a5 | 783 | |
af36000c DR |
784 | The C<isa> method returns I<true> if the object is a member of the |
785 | class in C<$class>, or a member of a subclass of C<$class>. | |
a2bdc9a5 | 786 | |
2898ff73 DR |
787 | If you override this method, it should never throw an exception. |
788 | ||
af36000c | 789 | =item DOES($role) |
003db2bd | 790 | X<DOES> |
bcb8f0e8 | 791 | |
af36000c DR |
792 | The C<DOES> method returns I<true> if its object claims to perform the |
793 | role C<$role>. By default, this is equivalent to C<isa>. This method is | |
794 | provided for use by object system extensions that implement roles, like | |
795 | C<Moose> and C<Role::Tiny>. | |
bcb8f0e8 | 796 | |
2898ff73 DR |
797 | You can also override C<DOES> directly in your own classes. If you |
798 | override this method, it should never throw an exception. | |
8d26c1a8 | 799 | |
af36000c | 800 | =item can($method) |
d74e8afc | 801 | X<can> |
a2bdc9a5 | 802 | |
8d26c1a8 DR |
803 | The C<can> method checks to see if the class or object it was called on |
804 | has a method named C<$method>. This checks for the method in the class | |
805 | and all of its parents. If the method exists, then a reference to the | |
806 | subroutine is returned. If it does not then C<undef> is returned. | |
b32b0a5d | 807 | |
af36000c | 808 | If your class responds to method calls via C<AUTOLOAD>, you may want to |
8d26c1a8 DR |
809 | overload C<can> to return a subroutine reference for methods which your |
810 | C<AUTOLOAD> method handles. | |
af36000c | 811 | |
2898ff73 DR |
812 | If you override this method, it should never throw an exception. |
813 | ||
af36000c | 814 | =item VERSION($need) |
d74e8afc | 815 | X<VERSION> |
760ac839 | 816 | |
af36000c DR |
817 | The C<VERSION> method returns the version number of the class |
818 | (package). | |
819 | ||
820 | If the C<$need> argument is given then it will check that the current | |
821 | version (as defined by the $VERSION variable in the package) is greater | |
822 | than or equal to C<$need>; it will die if this is not the case. This | |
823 | method is called automatically by the C<VERSION> form of C<use>. | |
a2bdc9a5 | 824 | |
003db2bd | 825 | use Package 1.2 qw(some imported subs); |
71be2cbc | 826 | # implies: |
003db2bd | 827 | Package->VERSION(1.2); |
a2bdc9a5 | 828 | |
af36000c DR |
829 | We recommend that you use this method to access another package's |
830 | version, rather than looking directly at C<$Package::VERSION>. The | |
831 | package you are looking at could have overridden the C<VERSION> method. | |
832 | ||
833 | We also recommend using this method to check whether a module has a | |
834 | sufficient version. The internal implementation uses the L<version> | |
835 | module to make sure that different types of version numbers are | |
836 | compared correctly. | |
837 | ||
a2bdc9a5 | 838 | =back |
839 | ||
af36000c DR |
840 | =head2 AUTOLOAD |
841 | X<AUTOLOAD> | |
842 | ||
843 | If you call a method that doesn't exist in a class, Perl will throw an | |
2898ff73 DR |
844 | error. However, if that class or any of its parent classes defines an |
845 | C<AUTOLOAD> method, that C<AUTOLOAD> method is called instead. | |
af36000c | 846 | |
2898ff73 DR |
847 | C<AUTOLOAD> is called as a regular method, and the caller will not know |
848 | the difference. Whatever value your C<AUTOLOAD> method returns is | |
849 | returned to the caller. | |
af36000c DR |
850 | |
851 | The fully qualified method name that was called is available in the | |
852 | C<$AUTOLOAD> package global for your class. Since this is a global, if | |
995ab4ef DR |
853 | you want to refer to do it without a package name prefix under C<strict |
854 | 'vars'>, you need to declare it. | |
af36000c | 855 | |
00c07ea6 DR |
856 | # XXX - this is a terrible way to implement accessors, but it makes |
857 | # for a simple example. | |
af36000c DR |
858 | our $AUTOLOAD; |
859 | sub AUTOLOAD { | |
860 | my $self = shift; | |
861 | ||
7168b251 DC |
862 | # Remove qualifier from original method name... |
863 | my $called = $AUTOLOAD =~ s/.*:://r; | |
af36000c | 864 | |
7168b251 | 865 | # Is there an attribute of that name? |
af36000c DR |
866 | die "No such attribute: $called" |
867 | unless exists $self->{$called}; | |
868 | ||
7168b251 | 869 | # If so, return it... |
af36000c DR |
870 | return $self->{$called}; |
871 | } | |
872 | ||
8d26c1a8 DR |
873 | sub DESTROY { } # see below |
874 | ||
af36000c DR |
875 | Without the C<our $AUTOLOAD> declaration, this code will not compile |
876 | under the L<strict> pragma. | |
877 | ||
2898ff73 DR |
878 | As the comment says, this is not a good way to implement accessors. |
879 | It's slow and too clever by far. However, you may see this as a way to | |
880 | provide accessors in older Perl code. See L<perlootut> for | |
881 | recommendations on OO coding in Perl. | |
af36000c DR |
882 | |
883 | If your class does have an C<AUTOLOAD> method, we strongly recommend | |
884 | that you override C<can> in your class as well. Your overridden C<can> | |
885 | method should return a subroutine reference for any method that your | |
886 | C<AUTOLOAD> responds to. | |
887 | ||
54310121 | 888 | =head2 Destructors |
d74e8afc | 889 | X<destructor> X<DESTROY> |
a0d0e21e | 890 | |
8d26c1a8 DR |
891 | When the last reference to an object goes away, the object is |
892 | destroyed. If you only have one reference to an object stored in a | |
893 | lexical scalar, the object is destroyed when that scalar goes out of | |
894 | scope. If you store the object in a package global, that object may not | |
895 | go out of scope until the program exits. | |
af36000c DR |
896 | |
897 | If you want to do something when the object is destroyed, you can | |
8d26c1a8 DR |
898 | define a C<DESTROY> method in your class. This method will always be |
899 | called by Perl at the appropriate time, unless the method is empty. | |
af36000c DR |
900 | |
901 | This is called just like any other method, with the object as the first | |
8d26c1a8 DR |
902 | argument. It does not receive any additional arguments. However, the |
903 | C<$_[0]> variable will be read-only in the destructor, so you cannot | |
904 | assign a value to it. | |
905 | ||
906 | If your C<DESTROY> method throws an error, this error will be ignored. | |
907 | It will not be sent to C<STDERR> and it will not cause the program to | |
908 | die. However, if your destructor is running inside an C<eval {}> block, | |
909 | then the error will change the value of C<$@>. | |
af36000c DR |
910 | |
911 | Because C<DESTROY> methods can be called at any time, you should | |
912 | localize any global variables you might update in your C<DESTROY>. In | |
913 | particular, if you use C<eval {}> you should localize C<$@>, and if you | |
914 | use C<system> or backticks, you should localize C<$?>. | |
915 | ||
8d26c1a8 DR |
916 | If you define an C<AUTOLOAD> in your class, then Perl will call your |
917 | C<AUTOLOAD> to handle the C<DESTROY> method. You can prevent this by | |
7168b251 DC |
918 | defining an empty C<DESTROY>, like we did in the autoloading example. |
919 | You can also check the value of C<$AUTOLOAD> and return without doing | |
920 | anything when called to handle C<DESTROY>. | |
8d26c1a8 DR |
921 | |
922 | =head3 Global Destruction | |
af36000c | 923 | |
8d26c1a8 DR |
924 | The order in which objects are destroyed during the global destruction |
925 | before the program exits is unpredictable. This means that any objects | |
926 | contained by your object may already have been destroyed. You should | |
927 | check that a contained object is defined before calling a method on it: | |
af36000c DR |
928 | |
929 | sub DESTROY { | |
930 | my $self = shift; | |
931 | ||
932 | $self->{handle}->close() if $self->{handle}; | |
933 | } | |
934 | ||
935 | You can use the C<${^GLOBAL_PHASE}> variable to detect if you are | |
8d26c1a8 | 936 | currently in the global destruction phase: |
af36000c DR |
937 | |
938 | sub DESTROY { | |
939 | my $self = shift; | |
940 | ||
941 | return if ${^GLOBAL_PHASE} eq 'DESTRUCT'; | |
942 | ||
943 | $self->{handle}->close(); | |
944 | } | |
945 | ||
946 | Note that this variable was added in Perl 5.14.0. If you want to detect | |
8d26c1a8 | 947 | the global destruction phase on older versions of Perl, you can use the |
af36000c DR |
948 | C<Devel::GlobalDestruction> module on CPAN. |
949 | ||
8d26c1a8 DR |
950 | If your C<DESTROY> method issues a warning during global destruction, |
951 | the Perl interpreter will append the string " during global | |
952 | destruction" the warning. | |
953 | ||
954 | During global destruction, Perl will always garbage collect objects | |
995ab4ef DR |
955 | before unblessed references. See L<perlhacktips/PERL_DESTRUCT_LEVEL> |
956 | for more information about global destruction. | |
8d26c1a8 | 957 | |
7168b251 | 958 | =head2 Non-Hash Objects |
af36000c | 959 | |
7168b251 DC |
960 | All the examples so far have shown objects based on a blessed hash. |
961 | However, it's possible to bless any type of data structure or referent, | |
962 | including scalars, globs, and subroutines. You may see this sort of | |
963 | thing when looking at code in the wild. | |
af36000c DR |
964 | |
965 | Here's an example of a module as a blessed scalar: | |
966 | ||
967 | package Time; | |
968 | ||
e011bc34 DR |
969 | use strict; |
970 | use warnings; | |
971 | ||
af36000c DR |
972 | sub new { |
973 | my $class = shift; | |
974 | ||
975 | my $time = time; | |
976 | return bless \$time, $class; | |
977 | } | |
978 | ||
979 | sub epoch { | |
980 | my $self = shift; | |
981 | return ${ $self }; | |
982 | } | |
983 | ||
984 | my $time = Time->new(); | |
985 | print $time->epoch(); | |
986 | ||
987 | =head2 Inside-Out objects | |
988 | ||
e011bc34 | 989 | In the past, the Perl community experimented with a technique called |
8d26c1a8 DR |
990 | "inside-out objects". An inside-out object stores its data outside of |
991 | the object's reference, indexed on a unique property of the object, | |
7168b251 DC |
992 | such as its memory address, rather than in the object itself. This has |
993 | the advantage of enforcing the encapsulation of object attributes, | |
994 | since their data is not stored in the object itself. | |
af36000c | 995 | |
e011bc34 | 996 | This technique was popular for a while (and was recommended in Damian |
7168b251 DC |
997 | Conway's I<Perl Best Practices>), but never achieved universal |
998 | adoption. The L<Object::InsideOut> module on CPAN provides a | |
999 | comprehensive implementation of this technique, and you may see it or | |
1000 | other inside-out modules in the wild. | |
af36000c | 1001 | |
e011bc34 DR |
1002 | Here is a simple example of the technique, using the |
1003 | L<Hash::Util::FieldHash> core module. This module was added to the core | |
1004 | to support inside-out object implementations. | |
1005 | ||
7168b251 | 1006 | package Time; |
e011bc34 DR |
1007 | |
1008 | use strict; | |
1009 | use warnings; | |
1010 | ||
1011 | use Hash::Util::FieldHash 'fieldhash'; | |
1012 | ||
7168b251 | 1013 | fieldhash my %time_for; |
e011bc34 DR |
1014 | |
1015 | sub new { | |
1016 | my $class = shift; | |
e011bc34 | 1017 | |
7168b251 DC |
1018 | my $self = bless \( my $object ), $class; |
1019 | ||
1020 | $time_for{$self} = time; | |
1021 | ||
1022 | return $self; | |
e011bc34 DR |
1023 | } |
1024 | ||
1025 | sub epoch { | |
1026 | my $self = shift; | |
1027 | ||
7168b251 | 1028 | return $time_for{$self}; |
e011bc34 DR |
1029 | } |
1030 | ||
7168b251 | 1031 | my $time = Time->new; |
e011bc34 DR |
1032 | print $time->epoch; |
1033 | ||
af36000c DR |
1034 | =head2 Pseudo-hashes |
1035 | ||
1036 | The pseudo-hash feature was an experimental feature introduced in | |
1037 | earlier versions of Perl and removed in 5.10.0. A pseudo-hash is an | |
1038 | array reference which can be accessed using named keys like a hash. You | |
1039 | may run in to some code in the wild which uses it. See the L<fields> | |
1040 | pragma for more information. | |
5a964f20 | 1041 | |
a0d0e21e LW |
1042 | =head1 SEE ALSO |
1043 | ||
8257a158 | 1044 | A kinder, gentler tutorial on object-oriented programming in Perl can |
af36000c DR |
1045 | be found in L<perlootut>. You should also check out L<perlmodlib> for |
1046 | some style guides on constructing both modules and classes. | |
1047 |