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