perl 5.000perl-5.000

[editor's note: this commit combines approximate 4 months of furious
releases of Andy Dougherty and Larry Wall - see pod/perlhist.pod for
details.  Andy notes that;
 
Alas neither my "Irwin AccuTrack" nor my DC 600A quarter-inch cartridge 
backup tapes from that era seem to be readable anymore.  I guess 13 years 
exceeds the shelf life for that backup technology :-(.
]

1 files changed, 367 insertions, 0 deletions

diff --git a/pod/perlbot.pod b/pod/perlbot.pod
new file mode 100644
index 0000000000..3df273be7d
--- /dev/null
+++ b/pod/perlbot.pod
@@ -0,0 +1,367 @@
+=head1 NAME
+
+perlbot - Bag'o Object Tricks For Perl5 (the BOT)
+
+=head1 INTRODUCTION
+
+The following collection of tricks and hints is intended to whet curious
+appetites about such things as the use of instance variables and the
+mechanics of object and class relationships.  The reader is encouraged to
+consult relevant textbooks for discussion of Object Oriented definitions and
+methodology.  This is not intended as a comprehensive guide to Perl5's
+object oriented features, nor should it be construed as a style guide.
+
+The Perl motto still holds:  There's more than one way to do it.
+
+=head1 INSTANCE VARIABLES
+
+An anonymous array or anonymous hash can be used to hold instance
+variables.  Named parameters are also demonstrated.
+
+	package Foo;
+
+	sub new {
+		my $type = shift;
+		my %params = @_;
+		my $self = {};
+		$self->{'High'} = $params{'High'};
+		$self->{'Low'}  = $params{'Low'};
+		bless $self;
+	}
+
+
+	package Bar;
+
+	sub new {
+		my $type = shift;
+		my %params = @_;
+		my $self = [];
+		$self->[0] = $params{'Left'};
+		$self->[1] = $params{'Right'};
+		bless $self;
+	}
+
+	package main;
+
+	$a = new Foo ( 'High' => 42, 'Low' => 11 );
+	print "High=$a->{'High'}\n";
+	print "Low=$a->{'Low'}\n";
+
+	$b = new Bar ( 'Left' => 78, 'Right' => 40 );
+	print "Left=$b->[0]\n";
+	print "Right=$b->[1]\n";
+
+
+=head1 SCALAR INSTANCE VARIABLES
+
+An anonymous scalar can be used when only one instance variable is needed.
+
+	package Foo;
+
+	sub new {
+		my $type = shift;
+		my $self;
+		$self = shift;
+		bless \$self;
+	}
+
+	package main;
+
+	$a = new Foo 42;
+	print "a=$$a\n";
+
+
+=head1 INSTANCE VARIABLE INHERITANCE
+
+This example demonstrates how one might inherit instance variables from a
+superclass for inclusion in the new class.  This requires calling the
+superclass's constructor and adding one's own instance variables to the new
+object.
+
+	package Bar;
+
+	sub new {
+		my $self = {};
+		$self->{'buz'} = 42;
+		bless $self;
+	}
+
+	package Foo;
+	@ISA = qw( Bar );
+
+	sub new {
+		my $self = new Bar;
+		$self->{'biz'} = 11;
+		bless $self;
+	}
+
+	package main;
+
+	$a = new Foo;
+	print "buz = ", $a->{'buz'}, "\n";
+	print "biz = ", $a->{'biz'}, "\n";
+
+
+
+=head1 OBJECT RELATIONSHIPS
+
+The following demonstrates how one might implement "containing" and "using"
+relationships between objects.
+
+	package Bar;
+
+	sub new {
+		my $self = {};
+		$self->{'buz'} = 42;
+		bless $self;
+	}
+
+	package Foo;
+
+	sub new {
+		my $self = {};
+		$self->{'Bar'} = new Bar ();
+		$self->{'biz'} = 11;
+		bless $self;
+	}
+
+	package main;
+
+	$a = new Foo;
+	print "buz = ", $a->{'Bar'}->{'buz'}, "\n";
+	print "biz = ", $a->{'biz'}, "\n";
+
+
+
+=head1 OVERRIDING SUPERCLASS METHODS
+
+The following example demonstrates how one might override a superclass
+method and then call the method after it has been overridden.  The
+Foo::Inherit class allows the programmer to call an overridden superclass
+method without actually knowing where that method is defined.
+
+
+	package Buz;
+	sub goo { print "here's the goo\n" }
+
+	package Bar; @ISA = qw( Buz );
+	sub google { print "google here\n" }
+
+	package Baz;
+	sub mumble { print "mumbling\n" }
+
+	package Foo;
+	@ISA = qw( Bar Baz );
+	@Foo::Inherit::ISA = @ISA;  # Access to overridden methods.
+
+	sub new { bless [] }
+	sub grr { print "grumble\n" }
+	sub goo {
+		my $self = shift;
+		$self->Foo::Inherit::goo();
+	}
+	sub mumble {
+		my $self = shift;
+		$self->Foo::Inherit::mumble();
+	}
+	sub google {
+		my $self = shift;
+		$self->Foo::Inherit::google();
+	}
+
+	package main;
+
+	$foo = new Foo;
+	$foo->mumble;
+	$foo->grr;
+	$foo->goo;
+	$foo->google;
+
+
+=head1 USING RELATIONSHIP WITH SDBM 
+
+This example demonstrates an interface for the SDBM class.  This creates a
+"using" relationship between the SDBM class and the new class Mydbm.
+
+	use SDBM_File;
+	use POSIX;
+
+	package Mydbm;
+
+	sub TIEHASH {
+	    my $self = shift;
+	    my $ref  = SDBM_File->new(@_);
+	    bless {'dbm' => $ref};
+	}
+	sub FETCH {
+	    my $self = shift;
+	    my $ref  = $self->{'dbm'};
+	    $ref->FETCH(@_);
+	}
+	sub STORE {
+	    my $self = shift; 
+	    if (defined $_[0]){
+		my $ref = $self->{'dbm'};
+		$ref->STORE(@_);
+	    } else {
+		die "Cannot STORE an undefined key in Mydbm\n";
+	    }
+	}
+
+	package main;
+
+	tie %foo, Mydbm, "Sdbm", O_RDWR|O_CREAT, 0640;
+	$foo{'bar'} = 123;
+	print "foo-bar = $foo{'bar'}\n";
+
+	tie %bar, Mydbm, "Sdbm2", O_RDWR|O_CREAT, 0640;
+	$bar{'Cathy'} = 456;
+	print "bar-Cathy = $bar{'Cathy'}\n";
+
+=head1 THINKING OF CODE REUSE
+
+One strength of Object-Oriented languages is the ease with which old code
+can use new code.  The following examples will demonstrate first how one can
+hinder code reuse and then how one can promote code reuse.
+
+This first example illustrates a class which uses a fully-qualified method
+call to access the "private" method BAZ().  The second example will show
+that it is impossible to override the BAZ() method.
+
+	package FOO;
+
+	sub new { bless {} }
+	sub bar {
+		my $self = shift;
+		$self->FOO::private::BAZ;
+	}
+
+	package FOO::private;
+
+	sub BAZ {
+		print "in BAZ\n";
+	}
+
+	package main;
+
+	$a = FOO->new;
+	$a->bar;
+
+Now we try to override the BAZ() method.  We would like FOO::bar() to call
+GOOP::BAZ(), but this cannot happen since FOO::bar() explicitly calls
+FOO::private::BAZ().
+
+	package FOO;
+
+	sub new { bless {} }
+	sub bar {
+		my $self = shift;
+		$self->FOO::private::BAZ;
+	}
+
+	package FOO::private;
+
+	sub BAZ {
+		print "in BAZ\n";
+	}
+
+	package GOOP;
+	@ISA = qw( FOO );
+	sub new { bless {} }
+
+	sub BAZ {
+		print "in GOOP::BAZ\n";
+	}
+
+	package main;
+
+	$a = GOOP->new;
+	$a->bar;
+
+To create reusable code we must modify class FOO, flattening class
+FOO::private.  The next example shows a reusable class FOO which allows the
+method GOOP::BAZ() to be used in place of FOO::BAZ().
+
+	package FOO;
+
+	sub new { bless {} }
+	sub bar {
+		my $self = shift;
+		$self->BAZ;
+	}
+
+	sub BAZ {
+		print "in BAZ\n";
+	}
+
+	package GOOP;
+	@ISA = qw( FOO );
+
+	sub new { bless {} }
+	sub BAZ {
+		print "in GOOP::BAZ\n";
+	}
+
+	package main;
+
+	$a = GOOP->new;
+	$a->bar;
+
+=head1 CLASS CONTEXT AND THE OBJECT
+
+Use the object to solve package and class context problems.  Everything a
+method needs should be available via the object or should be passed as a
+parameter to the method.
+
+A class will sometimes have static or global data to be used by the
+methods.  A subclass may want to override that data and replace it with new
+data.  When this happens the superclass may not know how to find the new
+copy of the data.
+
+This problem can be solved by using the object to define the context of the
+method.  Let the method look in the object for a reference to the data.  The
+alternative is to force the method to go hunting for the data ("Is it in my
+class, or in a subclass?  Which subclass?"), and this can be inconvenient
+and will lead to hackery.  It is better to just let the object tell the
+method where that data is located.
+
+	package Bar;
+
+	%fizzle = ( 'Password' => 'XYZZY' );
+
+	sub new {
+		my $self = {};
+		$self->{'fizzle'} = \%fizzle;
+		bless $self;
+	}
+
+	sub enter {
+		my $self = shift;
+	
+		# Don't try to guess if we should use %Bar::fizzle
+		# or %Foo::fizzle.  The object already knows which
+		# we should use, so just ask it.
+		#
+		my $fizzle = $self->{'fizzle'};
+
+		print "The word is ", $fizzle->{'Password'}, "\n";
+	}
+
+	package Foo;
+	@ISA = qw( Bar );
+
+	%fizzle = ( 'Password' => 'Rumple' );
+
+	sub new {
+		my $self = Bar->new;
+		$self->{'fizzle'} = \%fizzle;
+		bless $self;
+	}
+
+	package main;
+
+	$a = Bar->new;
+	$b = Foo->new;
+	$a->enter;
+	$b->enter;
+