This is a live mirror of the Perl 5 development currently hosted at
add OO tutorial for beginners (from Randal L. Schwartz
[perl5.git] / pod / perlboot.pod
1=head1 NAME
3perlboot - Beginner's Object-Oriented Tutorial
7If you're not familiar with objects from other languages, some of the
8other Perl object documentation may be a little daunting, such as
9L<perlobj>, a basic reference in using objects, and L<perltoot>, which
10introduces readers to the pecularities of Perl's object system in a
11tutorial way.
13So, let's take a different approach, presuming no prior object
14experience. It helps if you know about subroutines (L<perlsub>),
15references (L<perlref> et. seq.), and packages (L<perlmod>), so become
16familiar with those first if you haven't already.
18=head2 If we could talk to the animals...
20Let's let the animals talk for a moment:
22 sub Cow::speak {
23 print "a Cow goes moooo!\n";
24 }
25 sub Horse::speak {
26 print "a Horse goes neigh!\n";
27 }
28 sub Sheep::speak {
29 print "a Sheep goes baaaah!\n"
30 }
32 Cow::speak;
33 Horse::speak;
34 Sheep::speak;
36This results in:
38 a Cow goes moooo!
39 a Horse goes neigh!
40 a Sheep goes baaaah!
42Nothing spectacular here. Simple subroutines, albeit from separate
43packages, and called using the full package name. So let's create
44an entire pasture:
46 # Cow::speak, Horse::speak, Sheep::speak as before
47 @pasture = qw(Cow Cow Horse Sheep Sheep);
48 foreach $animal (@pasture) {
49 &{$animal."::speak"};
50 }
52This results in:
54 a Cow goes moooo!
55 a Cow goes moooo!
56 a Horse goes neigh!
57 a Sheep goes baaaah!
58 a Sheep goes baaaah!
60Wow. That symbolic coderef de-referencing there is pretty nasty.
61We're counting on C<no strict subs> mode, certainly not recommended
62for larger programs. And why was that necessary? Because the name of
63the package seems to be inseparable from the name of the subroutine we
64want to invoke within that package.
66Or is it?
68=head2 Introducing the method invocation arrow
70For now, let's say that C<Class-E<gt>method> invokes subroutine
71C<method> in package C<Class>. (Here, "Class" is used in its
72"category" meaning, not its "scholastic" meaning.) That's not
73completely accurate, but we'll do this one step at a time. Now let's
74use it like so:
76 # Cow::speak, Horse::speak, Sheep::speak as before
77 Cow->speak;
78 Horse->speak;
79 Sheep->speak;
81And once again, this results in:
83 a Cow goes moooo!
84 a Horse goes neigh!
85 a Sheep goes baaaah!
87That's not fun yet. Same number of characters, all constant, no
88variables. But yet, the parts are separable now. Watch:
90 $a = "Cow";
91 $a->speak; # invokes Cow->speak
93Ahh! Now that the package name has been parted from the subroutine
94name, we can use a variable package name. And this time, we've got
95something that works even when C<use strict refs> is enabled.
97=head2 Invoking a barnyard
99Let's take that new arrow invocation and put it back in the barnyard
102 sub Cow::speak {
103 print "a Cow goes moooo!\n";
104 }
105 sub Horse::speak {
106 print "a Horse goes neigh!\n";
107 }
108 sub Sheep::speak {
109 print "a Sheep goes baaaah!\n"
110 }
112 @pasture = qw(Cow Cow Horse Sheep Sheep);
113 foreach $animal (@pasture) {
114 $animal->speak;
115 }
117There! Now we have the animals all talking, and safely at that,
118without the use of symbolic coderefs.
120But look at all that common code. Each of the C<speak> routines has a
121similar structure: a C<print> operator and a string that contains
122common text, except for two of the words. It'd be nice if we could
123factor out the commonality, in case we decide later to change it all
124to C<says> instead of C<goes>.
126And we actually have a way of doing that without much fuss, but we
127have to hear a bit more about what the method invocation arrow is
128actually doing for us.
130=head2 The extra parameter of method invocation
132The invocation of:
134 Class->method(@args)
136attempts to invoke subroutine C<Class::method> as:
138 Class::method("Class", @args);
140(If the subroutine can't be found, "inheritance" kicks in, but we'll
141get to that later.) This means that we get the class name as the
142first parameter. So we can rewrite the C<Sheep> speaking subroutine
145 sub Sheep::speak {
146 my $class = shift;
147 print "a $class goes baaaah!\n";
148 }
150And the other two animals come out similarly:
152 sub Cow::speak {
153 my $class = shift;
154 print "a $class goes moooo!\n";
155 }
156 sub Horse::speak {
157 my $class = shift;
158 print "a $class goes neigh!\n";
159 }
161In each case, C<$class> will get the value appropriate for that
162subroutine. But once again, we have a lot of similar structure. Can
163we factor that out even further? Yes, by calling another method in
164the same class.
166=head2 Calling a second method to simplify things
168Let's call out from C<speak> to a helper method called C<sound>.
169This method provides the constant text for the sound itself.
171 { package Cow;
172 sub sound { "moooo" }
173 sub speak {
174 my $class = shift;
175 print "a $class goes ", $class->sound, "!\n"
176 }
177 }
179Now, when we call C<Cow-E<gt>speak>, we get a C<$class> of C<Cow> in
180C<speak>. This in turn selects the C<Cow-E<gt>sound> method, which
181returns C<moooo>. But how different would this be for the C<Horse>?
183 { package Horse;
184 sub sound { "neigh" }
185 sub speak {
186 my $class = shift;
187 print "a $class goes ", $class->sound, "!\n"
188 }
189 }
191Only the name of the package and the specific sound change. So can we
192somehow share the definition for C<speak> between the Cow and the
193Horse? Yes, with inheritance!
195=head2 Inheriting the windpipes
197We'll define a common subroutine package called C<Animal>, with the
198definition for C<speak>:
200 { package Animal;
201 sub speak {
202 my $class = shift;
203 print "a $class goes ", $class->sound, "!\n"
204 }
205 }
207Then, for each animal, we say it "inherits" from C<Animal>, along
208with the animal-specific sound:
210 { package Cow;
211 @ISA = qw(Animal);
212 sub sound { "moooo" }
213 }
215Note the added C<@ISA> array. We'll get to that in a minute.
217But what happens when we invoke C<Cow-E<gt>speak> now?
219First, Perl constructs the argument list. In this case, it's just
220C<Cow>. Then Perl looks for C<Cow::speak>. But that's not there, so
221Perl checks for the inheritance array C<@Cow::ISA>. It's there,
222and contains the single name C<Animal>.
224Perl next checks for C<speak> inside C<Animal> instead, as in
225C<Animal::speak>. And that's found, so Perl invokes that subroutine
226with the already frozen argument list.
228Inside the C<Animal::speak> subroutine, C<$class> becomes C<Cow> (the
229first argument). So when we get to the step of invoking
230C<$class-E<gt>sound>, it'll be looking for C<Cow-E<gt>sound>, which
231gets it on the first try without looking at C<@ISA>. Success!
233=head2 A few notes about @ISA
235This magical C<@ISA> variable (pronounced "is a" not "ice-uh"), has
236declared that C<Cow> "is a" C<Animal>. Note that it's an array,
237not a simple single value, because on rare occasions, it makes sense
238to have more than one parent class searched for the missing methods.
240If C<Animal> also had an C<@ISA>, then we'd check there too. The
241search is recursive, depth-first, left-to-right in each C<@ISA>.
242Typically, each C<@ISA> has only one element (multiple elements means
243multiple inheritance and multiple headaches), so we get a nice tree of
246When we turn on C<use strict>, we'll get complaints on C<@ISA>, since
247it's not a variable containing an explicit package name, nor is it a
248lexical ("my") variable. We can't make it a lexical variable though,
249so there's a couple of straightforward ways to handle that.
251The easiest is to just spell the package name out:
253 @Cow::ISA = qw(Animal);
255Or allow it as an implictly named package variable:
257 package Cow;
258 use vars qw(@ISA);
259 @ISA = qw(Animal);
261If you're bringing in the class from outside, via an object-oriented
262module, you change:
264 package Cow;
265 use Animal;
266 use vars qw(@ISA);
267 @ISA = qw(Animal);
269into just:
271 package Cow;
272 use base qw(Animal);
274And that's pretty darn compact.
276=head2 Overriding the methods
278Let's add a mouse, which can barely be heard:
280 # Animal package from before
281 { package Mouse;
282 @ISA = qw(Animal);
283 sub sound { "squeak" }
284 sub speak {
285 my $class = shift;
286 print "a $class goes ", $class->sound, "!\n";
287 print "[but you can barely hear it!]\n";
288 }
289 }
291 Mouse->speak;
293which results in:
295 a Mouse goes squeak!
296 [but you can barely hear it!]
298Here, C<Mouse> has its own speaking routine, so C<Mouse-E<gt>speak>
299doesn't immediately invoke C<Animal-E<gt>speak>. This is known as
300"overriding". In fact, we didn't even need to say that a C<Mouse> was
301an C<Animal> at all, since all of the methods needed for C<speak> are
302completely defined with C<Mouse>.
304But we've now duplicated some of the code from C<Animal-E<gt>speak>,
305and this can once again be a maintenance headache. So, can we avoid
306that? Can we say somehow that a C<Mouse> does everything any other
307C<Animal> does, but add in the extra comment? Sure!
309First, we can invoke the C<Animal::speak> method directly:
311 # Animal package from before
312 { package Mouse;
313 @ISA = qw(Animal);
314 sub sound { "squeak" }
315 sub speak {
316 my $class = shift;
317 Animal::speak($class);
318 print "[but you can barely hear it!]\n";
319 }
320 }
322Note that we have to include the C<$class> parameter (almost surely
323the value of C<"Mouse">) as the first parameter to C<Animal::speak>,
324since we've stopped using the method arrow. Why did we stop? Well,
325if we invoke C<Animal-E<gt>speak> there, the first parameter to the
326method will be C<"Animal"> not C<"Mouse">, and when time comes for it
327to call for the C<sound>, it won't have the right class to come back
328to this package.
330Invoking C<Animal::speak> directly is a mess, however. What if
331C<Animal::speak> didn't exist before, and was being inherited from a
332class mentioned in C<@Animal::ISA>? Because we are no longer using
333the method arrow, we get one and only one chance to hit the right
336Also note that the C<Animal> classname is now hardwired into the
337subroutine selection. This is a mess if someone maintains the code,
338changing C<@ISA> for <Mouse> and didn't notice C<Animal> there in
339C<speak>. So, this is probably not the right way to go.
341=head2 Starting the search from a different place
343A better solution is to tell Perl to search from a higher place
344in the inheritance chain:
346 # same Animal as before
347 { package Mouse;
348 # same @ISA, &sound as before
349 sub speak {
350 my $class = shift;
351 $class->Animal::speak;
352 print "[but you can barely hear it!]\n";
353 }
354 }
356Ahh. This works. Using this syntax, we start with C<Animal> to find
357C<speak>, and use all of C<Animal>'s inheritance chain if not found
358immediately. And yet the first parameter will be C<$class>, so the
359found C<speak> method will get C<Mouse> as its first entry, and
360eventually work its way back to C<Mouse::sound> for the details.
362But this isn't the best solution. We still have to keep the C<@ISA>
363and the initial search package coordinated. Worse, if C<Mouse> had
364multiple entries in C<@ISA>, we wouldn't necessarily know which one
365had actually defined C<speak>. So, is there an even better way?
367=head2 The SUPER way of doing things
369By changing the C<Animal> class to the C<SUPER> class in that
370invocation, we get a search of all of our super classes (classes
371listed in C<@ISA>) automatically:
373 # same Animal as before
374 { package Mouse;
375 # same @ISA, &sound as before
376 sub speak {
377 my $class = shift;
378 $class->SUPER::speak;
379 print "[but you can barely hear it!]\n";
380 }
381 }
383So, C<SUPER::speak> means look in the current package's C<@ISA> for
384C<speak>, invoking the first one found.
386=head2 Where we're at so far...
388So far, we've seen the method arrow syntax:
390 Class->method(@args);
392or the equivalent:
394 $a = "Class";
395 $a->method(@args);
397which constructs an argument list of:
399 ("Class", @args)
401and attempts to invoke
403 Class::method("Class", @Args);
405However, if C<Class::method> is not found, then C<@Class::ISA> is examined
406(recursively) to locate a package that does indeed contain C<method>,
407and that subroutine is invoked instead.
409Using this simple syntax, we have class methods, (multiple)
410inheritance, overriding, and extending. Using just what we've seen so
411far, we've been able to factor out common code, and provide a nice way
412to reuse implementations with variations. This is at the core of what
413objects provide, but objects also provide instance data, which we
414haven't even begun to cover.
416=head2 A horse is a horse, of course of course -- or is it?
418Let's start with the code for the C<Animal> class
419and the C<Horse> class:
421 { package Animal;
422 sub speak {
423 my $class = shift;
424 print "a $class goes ", $class->sound, "!\n"
425 }
426 }
427 { package Horse;
428 @ISA = qw(Animal);
429 sub sound { "neigh" }
430 }
432This lets us invoke C<Horse-E<gt>speak> to ripple upward to
433C<Animal::speak>, calling back to C<Horse::sound> to get the specific
434sound, and the output of:
436 a Horse goes neigh!
438But all of our Horse objects would have to be absolutely identical.
439If I add a subroutine, all horses automatically share it. That's
440great for making horses the same, but how do we capture the
441distinctions about an individual horse? For example, suppose I want
442to give my first horse a name. There's got to be a way to keep its
443name separate from the other horses.
445We can do that by drawing a new distinction, called an "instance".
446An "instance" is generally created by a class. In Perl, any reference
447can be an instance, so let's start with the simplest reference
448that can hold a horse's name: a scalar reference.
450 my $name = "Mr. Ed";
451 my $talking = \$name;
453So now C<$talking> is a reference to what will be the instance-specific
454data (the name). The final step in turning this into a real instance
455is with a special operator called C<bless>:
457 bless $talking, Horse;
459This operator stores information about the package named C<Horse> into
460the thing pointed at by the reference. At this point, we say
461C<$talking> is an instance of C<Horse>. That is, it's a specific
462horse. The reference is otherwise unchanged, and can still be used
463with traditional dereferencing operators.
465=head2 Invoking an instance method
467The method arrow can be used on instances, as well as names of
468packages (classes). So, let's get the sound that C<$talking> makes:
470 my $noise = $talking->sound;
472To invoke C<sound>, Perl first notes that C<$talking> is a blessed
473reference (and thus an instance). It then constructs an argument
474list, in this case from just C<($talking)>. (Later we'll see that
475arguments will take their place following the instance variable,
476just like with classes.)
478Now for the fun part: Perl takes the class in which the instance was
479blessed, in this case C<Horse>, and uses that to locate the subroutine
480to invoke the method. In this case, C<Horse::sound> is found directly
481(without using inheritance), yielding the final subroutine invocation:
483 Horse::sound($talking)
485Note that the first parameter here is still the instance, not the name
486of the class as before. We'll get C<neigh> as the return value, and
487that'll end up as the C<$noise> variable above.
489If Horse::sound had not been found, we'd be wandering up the
490C<@Horse::ISA> list to try to find the method in one of the
491superclasses, just as for a class method. The only difference between
492a class method and an instance method is whether the first parameter
493is a instance (a blessed reference) or a class name (a string).
495=head2 Accessing the instance data
497Because we get the instance as the first parameter, we can now access
498the instance-specific data. In this case, let's add a way to get at
499the name:
501 { package Horse;
502 @ISA = qw(Animal);
503 sub sound { "neigh" }
504 sub name {
505 my $self = shift;
506 $$self;
507 }
508 }
510Now we call for the name:
512 print $talking->name, " says ", $talking->sound, "\n";
514Inside C<Horse::name>, the C<@_> array contains just C<$talking>,
515which the C<shift> stores into C<$self>. (It's traditional to shift
516the first parameter off into a variable named C<$self> for instance
517methods, so stay with that unless you have strong reasons otherwise.)
518Then, C<$self> gets de-referenced as a scalar ref, yielding C<Mr. Ed>,
519and we're done with that. The result is:
521 Mr. Ed says neigh.
523=head2 How to build a horse
525Of course, if we constructed all of our horses by hand, we'd most
526likely make mistakes from time to time. We're also violating one of
527the properties of object-oriented programming, in that the "inside
528guts" of a Horse are visible. That's good if you're a veterinarian,
529but not if you just like to own horses. So, let's let the Horse class
530build a new horse:
532 { package Horse;
533 @ISA = qw(Animal);
534 sub sound { "neigh" }
535 sub name {
536 my $self = shift;
537 $$self;
538 }
539 sub named {
540 my $class = shift;
541 my $name = shift;
542 bless \$name, $class;
543 }
544 }
546Now with the new C<named> method, we can build a horse:
548 my $talking = Horse->named("Mr. Ed");
550Notice we're back to a class method, so the two arguments to
551C<Horse::named> are C<Horse> and C<Mr. Ed>. The C<bless> operator
552not only blesses C<$name>, it also returns the reference to C<$name>,
553so that's fine as a return value. And that's how to build a horse.
555=head2 Inheriting the constructor
557But was there anything specific to C<Horse> in that method? No. Therefore,
558it's also the same recipe for building anything else that inherited from
559C<Animal>, so let's put it there:
561 { package Animal;
562 sub speak {
563 my $class = shift;
564 print "a $class goes ", $class->sound, "!\n"
565 }
566 sub name {
567 my $self = shift;
568 $$self;
569 }
570 sub named {
571 my $class = shift;
572 my $name = shift;
573 bless \$name, $class;
574 }
575 }
576 { package Horse;
577 @ISA = qw(Animal);
578 sub sound { "neigh" }
579 }
581Ahh, but what happens if we invoke C<speak> on an instance?
583 my $talking = Horse->named("Mr. Ed");
584 $talking->speak;
586We get a debugging value:
588 a Horse=SCALAR(0xaca42ac) goes neigh!
590Why? Because the C<Animal::speak> routine is expecting a classname as
591its first parameter, not an instance. When the instance is passed in,
592we'll end up using a blessed scalar reference as a string, and that
593shows up as we saw it just now.
595=head2 Making a method work with either classes or instances
597All we need is for a method to detect if it is being called on a class
598or called on an instance. The most straightforward way is with the
599C<ref> operator. This returns a string (the classname) when used on a
600blessed reference, and C<undef> when used on a string (like a
601classname). Let's modify the C<name> method first to notice the change:
603 sub name {
604 my $either = shift;
605 ref $either
606 ? $$either # it's an instance, return name
607 : "an unnamed $either"; # it's a class, return generic
608 }
610Here, the C<?:> operator comes in handy to select either the
611dereference or a derived string. Now we can use this with either an
612instance or a class. Note that I've changed the first parameter
613holder to C<$either> to show that this is intended:
615 my $talking = Horse->named("Mr. Ed");
616 print Horse->name, "\n"; # prints "an unnamed Horse\n"
617 print $talking->name, "\n"; # prints "Mr Ed.\n"
619and now we'll fix C<speak> to use this:
621 sub speak {
622 my $either = shift;
623 print $either->name, " goes ", $either->sound, "\n";
624 }
626And since C<sound> already worked with either a class or an instance,
627we're done!
629=head2 Adding parameters to a method
631Let's train our animals to eat:
633 { package Animal;
634 sub named {
635 my $class = shift;
636 my $name = shift;
637 bless \$name, $class;
638 }
639 sub name {
640 my $either = shift;
641 ref $either
642 ? $$either # it's an instance, return name
643 : "an unnamed $either"; # it's a class, return generic
644 }
645 sub speak {
646 my $either = shift;
647 print $either->name, " goes ", $either->sound, "\n";
648 }
649 sub eat {
650 my $either = shift;
651 my $food = shift;
652 print $either->name, " eats $food.\n";
653 }
654 }
655 { package Horse;
656 @ISA = qw(Animal);
657 sub sound { "neigh" }
658 }
659 { package Sheep;
660 @ISA = qw(Animal);
661 sub sound { "baaaah" }
662 }
664And now try it out:
666 my $talking = Horse->named("Mr. Ed");
667 $talking->eat("hay");
668 Sheep->eat("grass");
670which prints:
672 Mr. Ed eats hay.
673 an unnamed Sheep eats grass.
675An instance method with parameters gets invoked with the instance,
676and then the list of parameters. So that first invocation is like:
678 Animal::eat($talking, "hay");
680=head2 More interesting instances
682What if an instance needs more data? Most interesting instances are
683made of many items, each of which can in turn be a reference or even
684another object. The easiest way to store these is often in a hash.
685The keys of the hash serve as the names of parts of the object (often
686called "instance variables" or "member variables"), and the
687corresponding values are, well, the values.
689But how do we turn the horse into a hash? Recall that an object was
690any blessed reference. We can just as easily make it a blessed hash
691reference as a blessed scalar reference, as long as everything that
692looks at the reference is changed accordingly.
694Let's make a sheep that has a name and a color:
696 my $bad = bless { Name => "Evil", Color => "black" }, Sheep;
698so C<$bad-E<gt>{Name}> has C<Evil>, and C<$bad-E<gt>{Color}> has
699C<black>. But we want to make C<$bad-E<gt>name> access the name, and
700that's now messed up because it's expecting a scalar reference. Not
701to worry, because that's pretty easy to fix up:
703 ## in Animal
704 sub name {
705 my $either = shift;
706 ref $either ?
707 $either->{Name} :
708 "an unnamed $either";
709 }
711And of course C<named> still builds a scalar sheep, so let's fix that
712as well:
714 ## in Animal
715 sub named {
716 my $class = shift;
717 my $name = shift;
718 my $self = { Name => $name, Color => $class->default_color };
719 bless $self, $class;
720 }
722What's this C<default_color>? Well, if C<named> has only the name,
723we still need to set a color, so we'll have a class-specific initial color.
724For a sheep, we might define it as white:
726 ## in Sheep
727 sub default_color { "white" }
729And then to keep from having to define one for each additional class,
730we'll define a "backstop" method that serves as the "default default",
731directly in C<Animal>:
733 ## in Animal
734 sub default_color { "brown" }
736Now, because C<name> and C<named> were the only methods that
737referenced the "structure" of the object, the rest of the methods can
738remain the same, so C<speak> still works as before.
740=head2 A horse of a different color
742But having all our horses be brown would be boring. So let's add a
743method or two to get and set the color.
745 ## in Animal
746 sub color {
747 $_[0]->{Color}
748 }
749 sub set_color {
750 $_[0]->{Color} = $_[1];
751 }
753Note the alternate way of accessing the arguments: C<$_[0]> is used
754in-place, rather than with a C<shift>. (This saves us a bit of time
755for something that may be invoked frequently.) And now we can fix
756that color for Mr. Ed:
758 my $talking = Horse->named("Mr. Ed");
759 $talking->set_color("black-and-white");
760 print $talking->name, " is colored ", $talking->color, "\n";
762which results in:
764 Mr. Ed is colored black-and-white
766=head2 Summary
768So, now we have class methods, constructors, instance methods,
769instance data, and even accessors. But that's still just the
770beginning of what Perl has to offer. We haven't even begun to talk
771about accessors that double as getters and setters, destructors,
772indirect object notation, subclasses that add instance data, per-class
773data, overloading, "isa" and "can" tests, C<UNIVERSAL> class, and so
774on. That's for the rest of the Perl documentation to cover.
775Hopefully, this gets you started, though.
777=head1 SEE ALSO
779For more information, see L<perlobj> (for all the gritty details about
780Perl objects, now that you've seen the basics), L<perltoot> (the
781tutorial for those who already know objects), L<perlbot> (for some
782more tricks), and books such as Damian Conway's excellent I<Object
783Oriented Perl>.
785=head1 COPYRIGHT
787Copyright (c) 1999, 2000 by Randal L. Schwartz and Stonehenge
788Consulting Services, Inc. Permission is hereby granted to distribute
789this document intact with the Perl distribution, and in accordance
790with the licenses of the Perl distribution; derived documents must
791include this copyright notice intact.
793Portions of this text have been derived from Perl Training materials
794originally appearing in the I<Packages, References, Objects, and
795Modules> course taught by instructors for Stonehenge Consulting
796Services, Inc. and used with permission.
798Portions of this text have been derived from materials originally
799appearing in I<Linux Magazine> and used with permission.