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