RE: blead: no longer supports %vd format

[p5sagit/p5-mst-13.2.git] / pod / perltoot.pod

diff --git a/pod/perltoot.pod b/pod/perltoot.pod
index 03372c7..4a212fb 100644 (file)
--- a/pod/perltoot.pod
+++ b/pod/perltoot.pod
@@ -224,23 +224,8 @@ The second argument is the class into which the referent will be blessed.
 By not assuming our own class as the default second argument and instead
 using the class passed into us, we make our constructor inheritable.
 
-While we're at it, let's make our constructor a bit more flexible.
-Rather than being uniquely a class method, we'll set it up so that
-it can be called as either a class method I<or> an object
-method.  That way you can say:
-
-    $me  = Person->new();
-    $him = $me->new();
-
-To do this, all we have to do is check whether what was passed in
-was a reference or not.  If so, we were invoked as an object method,
-and we need to extract the package (class) using the ref() function.
-If not, we just use the string passed in as the package name
-for blessing our referent.
-
     sub new {
-        my $proto = shift;
-        my $class = ref($proto) || $proto;
+        my $class = shift;
         my $self  = {};
         $self->{NAME}   = undef;
         $self->{AGE}    = undef;
@@ -401,8 +386,7 @@ it instead a file-scoped lexical, you should make these
 changes to your Person::new() constructor:
 
     sub new {
-        my $proto = shift;
-        my $class = ref($proto) || $proto;
+        my $class = shift;
         my $self  = {};
         $Census++;
         $self->{NAME}   = undef;
@@ -458,8 +442,7 @@ a public data member in the same way that NAME, AGE, and PEERS are.
 to perl version 5.004 we'll have to quote the field name.)
 
     sub new {
-        my $proto = shift;
-        my $class = ref($proto) || $proto;
+        my $class = shift;
         my $self  = {};
         $self->{NAME}     = undef;
         $self->{AGE}      = undef;
@@ -650,8 +633,7 @@ Ok.  To do this, we'll change Person::new() so that it supports
 a full name field this way:
 
     sub new {
-        my $proto = shift;
-        my $class = ref($proto) || $proto;
+        my $class = shift;
         my $self  = {};
         $self->{FULLNAME} = Fullname->new();
         $self->{AGE}      = undef;
@@ -683,8 +665,7 @@ by the appropriate name to access them:
     use strict;
 
     sub new {
-        my $proto = shift;
-        my $class = ref($proto) || $proto;
+        my $class = shift;
         my $self  = {
             TITLE       => undef,
             CHRISTIAN   => undef,
@@ -940,7 +921,8 @@ comes to the rescue here.
 This way it starts looking in my class's @ISA.  This only makes sense
 from I<within> a method call, though.  Don't try to access anything
 in SUPER:: from anywhere else, because it doesn't exist outside
-an overridden method call.
+an overridden method call. Note that C<SUPER> refers to the superclass of
+the current package, I<not> to the superclass of C<$self>.
 
 Things are getting a bit complicated here.  Have we done anything
 we shouldn't?  As before, one way to test whether we're designing
@@ -1008,8 +990,7 @@ know about its immediate superclass, but never vice-versa.)  So let's
 fix up Employee::new() this way:
 
     sub new {
-        my $proto = shift;
-        my $class = ref($proto) || $proto;
+        my $class = shift;
         my $self  = $class->SUPER::new();
         $self->{SALARY}        = undef;
         $self->{ID}            = undef;
@@ -1130,9 +1111,9 @@ above, just add this to Person.pm:
 
     our $VERSION = '1.1';
 
-and then in Employee.pm could you can say
+and then in Employee.pm you can say
 
-    use Employee 1.1;
+    use Person 1.1;
 
 And it would make sure that you have at least that version number or
 higher available.   This is not the same as loading in that exact version
@@ -1243,8 +1224,7 @@ different:
     package Person;
 
     sub new {
-        my $that  = shift;
-        my $class = ref($that) || $that;
+        my $class  = shift;
         my $self = {
            NAME  => undef,
            AGE   => undef,
@@ -1375,8 +1355,7 @@ constructor will look like when taking this approach:
     );
 
     sub new {
-       my $that  = shift;
-       my $class = ref($that) || $that;
+       my $class = shift;
        my $self  = {
            _permitted => \%fields,
            %fields,
@@ -1444,9 +1423,8 @@ Here's how to be careful:
     );
 
     sub new {
-       my $that  = shift;
-       my $class = ref($that) || $that;
-       my $self = bless $that->SUPER::new(), $class;
+       my $class = shift;
+       my $self  = $class->SUPER::new();
        my($element);
        foreach $element (keys %fields) {
            $self->{_permitted}->{$element} = $fields{$element};
@@ -1496,10 +1474,10 @@ Here's a simple example of using it:
     struct 'Fred' => {
         one        => '$',
         many       => '@',
-        profession => Jobbie,  # calls Jobbie->new()
+        profession => 'Jobbie',  # does not call Jobbie->new()
     };
 
-    $ob = Fred->new;
+    $ob = Fred->new(profession => Jobbie->new());
     $ob->one("hmmmm");
 
     $ob->many(0, "here");
@@ -1513,6 +1491,10 @@ You can declare types in the struct to be basic Perl types, or
 user-defined types (classes).  User types will be initialized by calling
 that class's new() method.
 
+Take care that the C<Jobbie> object is not created automatically by the
+C<Fred> class's new() method, so you should specify a C<Jobbie> object
+when you create an instance of C<Fred>.
+
 Here's a real-world example of using struct generation.  Let's say you
 wanted to override Perl's idea of gethostbyname() and gethostbyaddr() so
 that they would return objects that acted like C structures.  We don't
@@ -1650,8 +1632,7 @@ update value fields in the hash.  Convenient, eh?
 
     # this is the same as before...
     sub new {
-        my $that  = shift;
-        my $class = ref($that) || $that;
+        my $class = shift;
         my $self = {
            NAME  => undef,
            AGE   => undef,