| 1 | =encoding utf8 |
| 2 | |
| 3 | =for comment |
| 4 | Consistent formatting of this file is achieved with: |
| 5 | perl ./Porting/podtidy pod/perlobj.pod |
| 6 | |
| 7 | =head1 NAME |
| 8 | X<object> X<OOP> |
| 9 | |
| 10 | perlobj - Perl object reference |
| 11 | |
| 12 | =head1 DESCRIPTION |
| 13 | |
| 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. |
| 20 | |
| 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>. |
| 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: |
| 31 | |
| 32 | =over 4 |
| 33 | |
| 34 | =item 1. |
| 35 | |
| 36 | An object is simply a data structure that knows to which class it |
| 37 | belongs. |
| 38 | |
| 39 | =item 2. |
| 40 | |
| 41 | A class is simply a package. A class provides methods that expect to |
| 42 | operate on objects. |
| 43 | |
| 44 | =item 3. |
| 45 | |
| 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. |
| 48 | |
| 49 | =back |
| 50 | |
| 51 | Let's look at each of these principles in depth. |
| 52 | |
| 53 | =head2 An Object is Simply a Data Structure |
| 54 | X<object> X<bless> X<constructor> X<new> |
| 55 | |
| 56 | Unlike many other languages which support object orientation, Perl does |
| 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. |
| 64 | |
| 65 | Here is a simple constructor: |
| 66 | |
| 67 | package File; |
| 68 | |
| 69 | sub new { |
| 70 | my $class = shift; |
| 71 | |
| 72 | return bless {}, $class; |
| 73 | } |
| 74 | |
| 75 | The name C<new> isn't special. We could name our constructor something |
| 76 | else: |
| 77 | |
| 78 | package File; |
| 79 | |
| 80 | sub load { |
| 81 | my $class = shift; |
| 82 | |
| 83 | return bless {}, $class; |
| 84 | } |
| 85 | |
| 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. |
| 90 | |
| 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". |
| 95 | |
| 96 | We can also use a variable to store a reference to the data structure |
| 97 | that is being blessed as our object: |
| 98 | |
| 99 | sub new { |
| 100 | my $class = shift; |
| 101 | |
| 102 | my $self = {}; |
| 103 | bless $self, $class; |
| 104 | |
| 105 | return $self; |
| 106 | } |
| 107 | |
| 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: |
| 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 | } |
| 122 | |
| 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 |
| 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. |
| 130 | |
| 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 variety of ways, including using L<"Inside-Out objects"> |
| 135 | or modules from CPAN. |
| 136 | |
| 137 | =head3 Objects Are Blessed; Variables Are Not |
| 138 | |
| 139 | When we bless something, we are not blessing the variable which |
| 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: |
| 144 | |
| 145 | use Scalar::Util 'blessed'; |
| 146 | |
| 147 | my $foo = {}; |
| 148 | my $bar = $foo; |
| 149 | |
| 150 | bless $foo, 'Class'; |
| 151 | print blessed( $bar ); # prints "Class" |
| 152 | |
| 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). |
| 167 | |
| 168 | =head2 A Class is Simply a Package |
| 169 | X<class> X<package> X<@ISA> X<inheritance> |
| 170 | |
| 171 | Perl does not provide any special syntax for class definitions. A |
| 172 | package is simply a namespace containing variables and subroutines. The |
| 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. |
| 177 | |
| 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. |
| 181 | |
| 182 | It is possible to manually set C<@ISA>, and you may see this in older |
| 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. This is simply a list of scalars, each |
| 191 | of which is a string that corresponds to a package name. |
| 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()>. |
| 196 | The C<UNIVERSAL> class will I<never> appear in a package's C<@ISA> |
| 197 | variable. |
| 198 | |
| 199 | Perl I<only> provides method inheritance as a built-in feature. |
| 200 | Attribute inheritance is left up the class to implement. See the |
| 201 | L</Writing Accessors> section for details. |
| 202 | |
| 203 | =head2 A Method is Simply a Subroutine |
| 204 | X<method> |
| 205 | |
| 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 | |
| 219 | open my $fh, '>', $self->path() or die $!; |
| 220 | print {$fh} $self->data() or die $!; |
| 221 | close $fh or die $!; |
| 222 | } |
| 223 | |
| 224 | =head2 Method Invocation |
| 225 | X<invocation> X<method> X<arrow> X<< -> >> |
| 226 | |
| 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 |
| 230 | object (or class name), and the right hand side is the method name. |
| 231 | |
| 232 | my $pod = File->new( 'perlobj.pod', $data ); |
| 233 | $pod->save(); |
| 234 | |
| 235 | The C<< -> >> syntax is also used when dereferencing a reference. It |
| 236 | looks like the same operator, but these are two different operations. |
| 237 | |
| 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> |
| 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 |
| 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. |
| 249 | |
| 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 |
| 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. |
| 255 | |
| 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. |
| 259 | |
| 260 | =head2 Inheritance |
| 261 | X<inheritance> |
| 262 | |
| 263 | We already talked about the special C<@ISA> array and the L<parent> |
| 264 | pragma. |
| 265 | |
| 266 | When a class inherits from another class, any methods defined in the |
| 267 | parent class are available to the child class. If you attempt to call a |
| 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. |
| 270 | |
| 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 |
| 279 | C<save()> method. If Perl cannot find a C<save()> method anywhere in |
| 280 | the inheritance hierarchy, it will die. |
| 281 | |
| 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. |
| 286 | |
| 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. |
| 290 | |
| 291 | sub save { |
| 292 | my $self = shift; |
| 293 | |
| 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 |
| 299 | use it for regular subroutine calls or class methods: |
| 300 | |
| 301 | SUPER::save($thing); # FAIL: looks for save() sub in package SUPER |
| 302 | |
| 303 | SUPER->save($thing); # FAIL: looks for save() method in class |
| 304 | # SUPER |
| 305 | |
| 306 | $thing->SUPER::save(); # Okay: looks for save() method in parent |
| 307 | # classes |
| 308 | |
| 309 | |
| 310 | =head3 How SUPER is Resolved |
| 311 | X<SUPER> |
| 312 | |
| 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 |
| 315 | important, because it lets methods at different levels within a deep |
| 316 | inheritance hierarchy each correctly call their respective parent |
| 317 | methods. |
| 318 | |
| 319 | package A; |
| 320 | |
| 321 | sub new { |
| 322 | return bless {}, shift; |
| 323 | } |
| 324 | |
| 325 | sub speak { |
| 326 | my $self = shift; |
| 327 | |
| 328 | say 'A'; |
| 329 | } |
| 330 | |
| 331 | package B; |
| 332 | |
| 333 | use parent -norequire, 'A'; |
| 334 | |
| 335 | sub speak { |
| 336 | my $self = shift; |
| 337 | |
| 338 | $self->SUPER::speak(); |
| 339 | |
| 340 | say 'B'; |
| 341 | } |
| 342 | |
| 343 | package C; |
| 344 | |
| 345 | use parent -norequire, 'B'; |
| 346 | |
| 347 | sub speak { |
| 348 | my $self = shift; |
| 349 | |
| 350 | $self->SUPER::speak(); |
| 351 | |
| 352 | say 'C'; |
| 353 | } |
| 354 | |
| 355 | my $c = C->new(); |
| 356 | $c->speak(); |
| 357 | |
| 358 | In this example, we will get the following output: |
| 359 | |
| 360 | A |
| 361 | B |
| 362 | C |
| 363 | |
| 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 |
| 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). |
| 369 | |
| 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> |
| 372 | resolution will be done based on the original package. |
| 373 | |
| 374 | =head3 Multiple Inheritance |
| 375 | X<multiple inheritance> |
| 376 | |
| 377 | Multiple inheritance often indicates a design problem, but Perl always |
| 378 | gives you enough rope to hang yourself with if you ask for it. |
| 379 | |
| 380 | To declare multiple parents, you simply need to pass multiple class |
| 381 | names to C<use parent>: |
| 382 | |
| 383 | package MultiChild; |
| 384 | |
| 385 | use parent 'Parent1', 'Parent2'; |
| 386 | |
| 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 |
| 395 | | |
| 396 | Parent |
| 397 | | |
| 398 | Child |
| 399 | |
| 400 | If we call a method on a C<Child> object and that method is not defined |
| 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. |
| 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 |
| 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. |
| 415 | |
| 416 | SharedGreatGrandParent |
| 417 | / \ |
| 418 | PaternalGrandparent MaternalGrandparent |
| 419 | \ / |
| 420 | Father Mother |
| 421 | \ / |
| 422 | Child |
| 423 | |
| 424 | So given the diagram above, Perl will search C<Child>, C<Father>, |
| 425 | C<PaternalGrandparent>, C<SharedGreatGrandParent>, C<Mother>, and |
| 426 | finally C<MaternalGrandparent>. This may be a problem because now we're |
| 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>). |
| 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 |
| 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>, |
| 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. |
| 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 |
| 467 | constructor is simply a class method that returns a reference to a new |
| 468 | object. |
| 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 |
| 489 | itself. Remember, under the hood, this object is still just a hash. |
| 490 | Later, we'll write accessors to manipulate this data. |
| 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 | |
| 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 |
| 518 | object is an anonymous hash, we can store the attribute values in the |
| 519 | hash using the attribute name as the key. |
| 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 | |
| 525 | This has several advantages. Accessors make it easier to change the |
| 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 |
| 535 | use the accessors rather than having to know how a parent class is |
| 536 | implemented internally. |
| 537 | |
| 538 | =head3 Writing Accessors |
| 539 | X<accessor> |
| 540 | |
| 541 | As with constructors, Perl provides no special accessor declaration |
| 542 | syntax, so classes must provide explicitly written accessor methods. |
| 543 | There are two common types of accessors, read-only and read-write. |
| 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 |
| 574 | of accessors by hand is also incredibly tedious. There are a lot of |
| 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> |
| 580 | |
| 581 | Perl supports several other ways to call methods besides the C<< |
| 582 | $object->method() >> usage we've seen so far. |
| 583 | |
| 584 | =head3 Method Names as Strings |
| 585 | |
| 586 | Perl lets you use a scalar variable containing a string as a method |
| 587 | name: |
| 588 | |
| 589 | my $file = File->new( $path, $data ); |
| 590 | |
| 591 | my $method = 'save'; |
| 592 | $file->$method(); |
| 593 | |
| 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. |
| 597 | |
| 598 | =head3 Class Names as Strings |
| 599 | |
| 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 | |
| 610 | You can also use a subroutine reference as a method: |
| 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 | |
| 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() ) }; |
| 635 | $file->${ returns_ref_to_sub_ref() }; |
| 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 |
| 644 | methods on it. Additionally, you can call methods on the C<STDIN>, |
| 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 | |
| 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 sometimes interprets a bareword's meaning |
| 658 | incorrectly. 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 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()> |
| 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: |
| 670 | |
| 671 | Class::->new() |
| 672 | |
| 673 | Perl will always interpret this as a method call. |
| 674 | |
| 675 | Alternatively, you can quote the class name: |
| 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 as |
| 689 | it can confuse the Perl interpreter. See below for more details.> |
| 690 | |
| 691 | Perl supports another method invocation syntax called "indirect object" |
| 692 | notation. This syntax is called "indirect" because the method comes |
| 693 | before the object it is being invoked on. |
| 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 |
| 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. |
| 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 |
| 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! |
| 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 | |
| 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 | |
| 726 | =head2 C<bless>, C<blessed>, and C<ref> |
| 727 | |
| 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 |
| 730 | can take either one or two arguments: |
| 731 | |
| 732 | my $object = bless {}, $class; |
| 733 | my $object = bless {}; |
| 734 | |
| 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. |
| 738 | |
| 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 |
| 741 | across it in existing code. |
| 742 | |
| 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. |
| 746 | |
| 747 | use Scalar::Util 'blessed'; |
| 748 | |
| 749 | if ( defined blessed($thing) ) { ... } |
| 750 | |
| 751 | If C<$thing> refers to an object, then this function returns the name |
| 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. |
| 760 | |
| 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. |
| 765 | |
| 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. |
| 769 | |
| 770 | =head2 The UNIVERSAL Class |
| 771 | X<UNIVERSAL> |
| 772 | |
| 773 | All classes automatically inherit from the L<UNIVERSAL> class, which is |
| 774 | built-in to the Perl core. This class provides a number of methods, all |
| 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, |
| 777 | we recommend that you follow the built-in semantics described below. |
| 778 | |
| 779 | =over 4 |
| 780 | |
| 781 | =item isa($class) |
| 782 | X<isa> |
| 783 | |
| 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>. |
| 786 | |
| 787 | If you override this method, it should never throw an exception. |
| 788 | |
| 789 | =item DOES($role) |
| 790 | X<DOES> |
| 791 | |
| 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>. |
| 796 | |
| 797 | You can also override C<DOES> directly in your own classes. If you |
| 798 | override this method, it should never throw an exception. |
| 799 | |
| 800 | =item can($method) |
| 801 | X<can> |
| 802 | |
| 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. |
| 807 | |
| 808 | If your class responds to method calls via C<AUTOLOAD>, you may want to |
| 809 | overload C<can> to return a subroutine reference for methods which your |
| 810 | C<AUTOLOAD> method handles. |
| 811 | |
| 812 | If you override this method, it should never throw an exception. |
| 813 | |
| 814 | =item VERSION($need) |
| 815 | X<VERSION> |
| 816 | |
| 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>. |
| 824 | |
| 825 | use Package 1.2 qw(some imported subs); |
| 826 | # implies: |
| 827 | Package->VERSION(1.2); |
| 828 | |
| 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 | |
| 838 | =back |
| 839 | |
| 840 | =head2 AUTOLOAD |
| 841 | X<AUTOLOAD> |
| 842 | |
| 843 | If you call a method that doesn't exist in a class, Perl will throw an |
| 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. |
| 846 | |
| 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. |
| 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 |
| 853 | you want to refer to do it without a package name prefix under C<strict |
| 854 | 'vars'>, you need to declare it. |
| 855 | |
| 856 | # XXX - this is a terrible way to implement accessors, but it makes |
| 857 | # for a simple example. |
| 858 | our $AUTOLOAD; |
| 859 | sub AUTOLOAD { |
| 860 | my $self = shift; |
| 861 | |
| 862 | # Remove qualifier from original method name... |
| 863 | my $called = $AUTOLOAD =~ s/.*:://r; |
| 864 | |
| 865 | # Is there an attribute of that name? |
| 866 | die "No such attribute: $called" |
| 867 | unless exists $self->{$called}; |
| 868 | |
| 869 | # If so, return it... |
| 870 | return $self->{$called}; |
| 871 | } |
| 872 | |
| 873 | sub DESTROY { } # see below |
| 874 | |
| 875 | Without the C<our $AUTOLOAD> declaration, this code will not compile |
| 876 | under the L<strict> pragma. |
| 877 | |
| 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. |
| 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 | |
| 888 | =head2 Destructors |
| 889 | X<destructor> X<DESTROY> |
| 890 | |
| 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. |
| 896 | |
| 897 | If you want to do something when the object is destroyed, you can |
| 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. |
| 900 | |
| 901 | This is called just like any other method, with the object as the first |
| 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<$@>. |
| 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 | |
| 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 |
| 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>. |
| 921 | |
| 922 | =head3 Global Destruction |
| 923 | |
| 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: |
| 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 |
| 936 | currently in the global destruction phase: |
| 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 |
| 947 | the global destruction phase on older versions of Perl, you can use the |
| 948 | C<Devel::GlobalDestruction> module on CPAN. |
| 949 | |
| 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 |
| 955 | before unblessed references. See L<perlhacktips/PERL_DESTRUCT_LEVEL> |
| 956 | for more information about global destruction. |
| 957 | |
| 958 | =head2 Non-Hash Objects |
| 959 | |
| 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. |
| 964 | |
| 965 | Here's an example of a module as a blessed scalar: |
| 966 | |
| 967 | package Time; |
| 968 | |
| 969 | use strict; |
| 970 | use warnings; |
| 971 | |
| 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 | |
| 989 | In the past, the Perl community experimented with a technique called |
| 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, |
| 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. |
| 995 | |
| 996 | This technique was popular for a while (and was recommended in Damian |
| 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. |
| 1001 | |
| 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 | |
| 1006 | package Time; |
| 1007 | |
| 1008 | use strict; |
| 1009 | use warnings; |
| 1010 | |
| 1011 | use Hash::Util::FieldHash 'fieldhash'; |
| 1012 | |
| 1013 | fieldhash my %time_for; |
| 1014 | |
| 1015 | sub new { |
| 1016 | my $class = shift; |
| 1017 | |
| 1018 | my $self = bless \( my $object ), $class; |
| 1019 | |
| 1020 | $time_for{$self} = time; |
| 1021 | |
| 1022 | return $self; |
| 1023 | } |
| 1024 | |
| 1025 | sub epoch { |
| 1026 | my $self = shift; |
| 1027 | |
| 1028 | return $time_for{$self}; |
| 1029 | } |
| 1030 | |
| 1031 | my $time = Time->new; |
| 1032 | print $time->epoch; |
| 1033 | |
| 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. |
| 1041 | |
| 1042 | =head1 SEE ALSO |
| 1043 | |
| 1044 | A kinder, gentler tutorial on object-oriented programming in Perl can |
| 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 | |