This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
more typo fix for perlxstut.pod
[perl5.git] / pod / perlboot.pod
index b3e9c53..5aa6179 100644 (file)
@@ -253,7 +253,7 @@ The easiest is to just spell the package name out:
 
     @Cow::ISA = qw(Animal);
 
-Or declare it as package global variable:
+Or declare it as package global variable:
 
     package Cow;
     our @ISA = qw(Animal);
@@ -442,7 +442,7 @@ variations.
 
 Now, what about data?
 
-=head2 A horse is a horse, of course of course -- or is it?
+=head2 A horse is a horse, of course of course, or is it?
 
 Let's start with the code for the C<Animal> class
 and the C<Horse> class:
@@ -504,7 +504,7 @@ reference (and thus an instance).  It then constructs an argument
 list, as per usual.
 
 Now for the fun part: Perl takes the class in which the instance was
-blessed, in this case C<Horse>, and uses that calss to locate the
+blessed, in this case C<Horse>, and uses that class to locate the
 subroutine. In this case, C<Horse::sound> is found directly (without
 using inheritance). In the end, it is as though our initial line were
 written as follows:
@@ -538,7 +538,7 @@ the name:
 
 Inside C<Horse::name>, the C<@_> array contains:
 
-    (C<$horse>, "some", "unnecessary", "args")
+    ($horse, "some", "unnecessary", "args")
 
 so the C<shift> stores C<$horse> into C<$self>. Then, C<$self> gets
 de-referenced with C<$$self> as normal, yielding C<"Mr. Ed">.
@@ -561,31 +561,32 @@ Of course, if we constructed all of our horses by hand, we'd most
 likely make mistakes from time to time.  We're also violating one of
 the properties of object-oriented programming, in that the "inside
 guts" of a Horse are visible.  That's good if you're a veterinarian,
-but not if you just like to own horses.  So, let's let the Horse class
-build a new horse:
+but not if you just like to own horses.  So, let's have the Horse
+class handle the details inside a class method:
 
   { package Horse;
     @ISA = qw(Animal);
     sub sound { "neigh" }
     sub name {
-      my $self = shift;
+      my $self = shift;     # instance method, so use $self
       $$self;
     }
     sub named {
-      my $class = shift;
+      my $class = shift;    # class method, so use $class
       my $name = shift;
       bless \$name, $class;
     }
   }
 
-Now with the new C<named> method, we can build a horse:
+Now with the new C<named> method, we can build a horse as follows:
 
   my $horse = Horse->named("Mr. Ed");
 
 Notice we're back to a class method, so the two arguments to
 C<Horse::named> are C<Horse> and C<Mr. Ed>.  The C<bless> operator
-not only blesses C<$name>, it also returns the reference to C<$name>,
-so that's fine as a return value.  And that's how to build a horse.
+not only blesses C<\$name>, it also returns that reference.
+
+This C<Horse::named> method is called a "constructor".
 
 We've called the constructor C<named> here, so that it quickly denotes
 the constructor's argument as the name for this particular C<Horse>.
@@ -602,7 +603,7 @@ right?)
 
 But was there anything specific to C<Horse> in that method?  No.  Therefore,
 it's also the same recipe for building anything else that inherited from
-C<Animal>, so let's put it there:
+C<Animal>, so let's put C<name> and C<named> there:
 
   { package Animal;
     sub speak {
@@ -648,9 +649,7 @@ classname).  Let's modify the C<name> method first to notice the change:
 
   sub name {
     my $either = shift;
-    ref $either
-      ? $$either # it's an instance, return name
-      : "an unnamed $either"; # it's a class, return generic
+    ref $either ? $$either : "Any $either";
   }
 
 Here, the C<?:> operator comes in handy to select either the
@@ -659,7 +658,7 @@ instance or a class.  Note that I've changed the first parameter
 holder to C<$either> to show that this is intended:
 
   my $horse = Horse->named("Mr. Ed");
-  print Horse->name, "\n"; # prints "an unnamed Horse\n"
+  print Horse->name, "\n"; # prints "Any Horse\n"
   print $horse->name, "\n"; # prints "Mr Ed.\n"
 
 and now we'll fix C<speak> to use this:
@@ -684,9 +683,7 @@ Let's train our animals to eat:
     }
     sub name {
       my $either = shift;
-      ref $either
-        ? $$either # it's an instance, return name
-        : "an unnamed $either"; # it's a class, return generic
+      ref $either ? $$either : "Any $either";
     }
     sub speak {
       my $either = shift;
@@ -716,7 +713,7 @@ And now try it out:
 which prints:
 
   Mr. Ed eats hay.
-  an unnamed Sheep eats grass.
+  Any Sheep eats grass.
 
 An instance method with parameters gets invoked with the instance,
 and then the list of parameters.  So that first invocation is like:
@@ -744,42 +741,77 @@ Let's make a sheep that has a name and a color:
 so C<< $bad->{Name} >> has C<Evil>, and C<< $bad->{Color} >> has
 C<black>.  But we want to make C<< $bad->name >> access the name, and
 that's now messed up because it's expecting a scalar reference.  Not
-to worry, because that's pretty easy to fix up:
+to worry, because that's pretty easy to fix up.
+
+One solution is to override C<Animal::name> and C<Animal::named> by
+defining them anew in C<Sheep>, but then any methods added later to
+C<Animal> might still mess up, and we'd have to override all of those
+too. Therefore, it's never a good idea to define the data layout in a
+way that's different from the data layout of the base classes. In fact,
+it's a good idea to use blessed hash references in all cases. Also, this
+is why it's important to have constructors do the low-level work. So,
+let's redefine C<Animal>:
 
   ## in Animal
   sub name {
     my $either = shift;
-    ref $either ?
-      $either->{Name} :
-      "an unnamed $either";
+    ref $either ? $either->{Name} : "Any $either";
   }
-
-And of course C<named> still builds a scalar sheep, so let's fix that
-as well:
-
-  ## in Animal
   sub named {
     my $class = shift;
     my $name = shift;
-    my $self = { Name => $name, Color => $class->default_color };
+    my $self = { Name => $name };
     bless $self, $class;
   }
 
+Of course, we still need to override C<named> in order to handle
+constructing a C<Sheep> with a certain color:
+
+  ## in Sheep
+  sub named {
+    my ($class, $name) = @_;
+    my $self = $class->SUPER::named(@_);
+    $$self{Color} = $class->default_color;
+    $self
+  }
+
+(Note that C<@_> contains the parameters to C<named>.)
+
 What's this C<default_color>?  Well, if C<named> has only the name,
-we still need to set a color, so we'll have a class-specific initial color.
+we still need to set a color, so we'll have a class-specific default color.
 For a sheep, we might define it as white:
 
   ## in Sheep
   sub default_color { "white" }
 
-And then to keep from having to define one for each additional class,
-we'll define a "backstop" method that serves as the "default default",
-directly in C<Animal>:
+Now:
+
+  my $sheep = Sheep->named("Bad");
+  print $sheep->{Color}, "\n";
+
+outputs:
+
+  white
+
+Now, there's nothing particularly specific to C<Sheep> when it comes
+to color, so let's remove C<Sheep::named> and implement C<Animal::named>
+to handle color instead:
+
+  ## in Animal
+  sub named {
+    my ($class, $name) = @_;
+    my $self = { Name => $name, Color => $class->default_color };
+    bless $self, $class;
+  }
+
+And then to keep from having to define C<default_color> for each additional
+class, we'll define a method that serves as the "default default" directly
+in C<Animal>:
 
   ## in Animal
   sub default_color { "brown" }
 
-Now, because C<name> and C<named> were the only methods that
+Of course, because C<name> and C<named> were the only methods that
 referenced the "structure" of the object, the rest of the methods can
 remain the same, so C<speak> still works as before.
 
@@ -811,14 +843,13 @@ which results in:
 
 =head2 Summary
 
-So, now we have class methods, constructors, instance methods,
-instance data, and even accessors.  But that's still just the
-beginning of what Perl has to offer.  We haven't even begun to talk
-about accessors that double as getters and setters, destructors,
-indirect object notation, subclasses that add instance data, per-class
-data, overloading, "isa" and "can" tests, C<UNIVERSAL> class, and so
-on.  That's for the rest of the Perl documentation to cover.
-Hopefully, this gets you started, though.
+So, now we have class methods, constructors, instance methods, instance
+data, and even accessors. But that's still just the beginning of what
+Perl has to offer. We haven't even begun to talk about accessors that
+double as getters and setters, destructors, indirect object notation,
+overloading, "isa" and "can" tests, the C<UNIVERSAL> class, and so on.
+That's for the rest of the Perl documentation to cover. Hopefully, this
+gets you started, though.
 
 =head1 SEE ALSO
 
@@ -835,10 +866,14 @@ Class::MethodMaker and Tie::SecureHash
 =head1 COPYRIGHT
 
 Copyright (c) 1999, 2000 by Randal L. Schwartz and Stonehenge
-Consulting Services, Inc.  Permission is hereby granted to distribute
-this document intact with the Perl distribution, and in accordance
-with the licenses of the Perl distribution; derived documents must
-include this copyright notice intact.
+Consulting Services, Inc.
+
+Copyright (c) 2009 by Michael F. Witten.
+
+Permission is hereby granted to distribute this document intact with
+the Perl distribution, and in accordance with the licenses of the Perl
+distribution; derived documents must include this copyright notice
+intact.
 
 Portions of this text have been derived from Perl Training materials
 originally appearing in the I<Packages, References, Objects, and