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