perl5.005_03 (stock)

1 files changed, 48 insertions, 18 deletions

diff --git a/gnu/usr.bin/perl/pod/perltie.pod b/gnu/usr.bin/perl/pod/perltie.pod
index c6eb7156ce3..665265818d3 100644
--- a/gnu/usr.bin/perl/pod/perltie.pod
+++ b/gnu/usr.bin/perl/pod/perltie.pod
@@ -23,7 +23,7 @@ Now you can.
 The tie() function binds a variable to a class (package) that will provide
 the implementation for access methods for that variable.  Once this magic
 has been performed, accessing a tied variable automatically triggers
-method calls in the proper class.  All of the complexity of the class is
+method calls in the proper class.  The complexity of the class is
 hidden behind magic methods calls.  The method names are in ALL CAPS,
 which is a convention that Perl uses to indicate that they're called
 implicitly rather than explicitly--just like the BEGIN() and END()
@@ -180,17 +180,26 @@ TIESCALAR classes are certainly possible.
 =head2 Tying Arrays
 
 A class implementing a tied ordinary array should define the following
-methods: TIEARRAY, FETCH, STORE, and perhaps DESTROY.
+methods: TIEARRAY, FETCH, STORE, FETCHSIZE, STORESIZE and perhaps DESTROY. 
 
-B<WARNING>: Tied arrays are I<incomplete>.  They are also distinctly lacking
-something for the C<$#ARRAY> access (which is hard, as it's an lvalue), as
-well as the other obvious array functions, like push(), pop(), shift(),
-unshift(), and splice().
+FETCHSIZE and STORESIZE are used to provide C<$#array> and
+equivalent C<scalar(@array)> access.
+    
+The methods POP, PUSH, SHIFT, UNSHIFT, SPLICE are required if the perl
+operator with the corresponding (but lowercase) name is to operate on the
+tied array. The B<Tie::Array> class can be used as a base class to implement
+these in terms of the basic five methods above.  
+
+In addition EXTEND will be called when perl would have pre-extended 
+allocation in a real array.
+
+This means that tied arrays are now I<complete>. The example below needs
+upgrading to illustrate this. (The documentation in B<Tie::Array> is more
+complete.)
 
 For this discussion, we'll implement an array whose indices are fixed at
 its creation.  If you try to access anything beyond those bounds, you'll
-take an exception.  (Well, if you access an individual element; an
-aggregate assignment would be missed.) For example:
+take an exception.  For example:
 
     require Bounded_Array;
     tie @ary, 'Bounded_Array', 2;
@@ -594,9 +603,9 @@ or have auxiliary state to clean up.  Here's a very simple function:
 
 =back
 
-Note that functions such as keys() and values() may return huge array
-values when used on large objects, like DBM files.  You may prefer to
-use the each() function to iterate over such.  Example:
+Note that functions such as keys() and values() may return huge lists
+when used on large objects, like DBM files.  You may prefer to use the
+each() function to iterate over such.  Example:
 
     # print out history file offsets
     use NDBM_File;
@@ -611,8 +620,8 @@ use the each() function to iterate over such.  Example:
 This is partially implemented now.
 
 A class implementing a tied filehandle should define the following
-methods: TIEHANDLE, at least one of PRINT, PRINTF, READLINE, GETC, or READ,
-and possibly DESTROY.
+methods: TIEHANDLE, at least one of PRINT, PRINTF, WRITE, READLINE, GETC,
+READ, and possibly CLOSE and DESTROY.
 
 It is especially useful when perl is embedded in some other program,
 where output to STDOUT and STDERR may have to be redirected in some
@@ -632,6 +641,17 @@ hold some internal information.
 
     sub TIEHANDLE { print "<shout>\n"; my $i; bless \$i, shift }
 
+=item WRITE this, LIST
+
+This method will be called when the handle is written to via the
+C<syswrite> function.
+
+    sub WRITE {
+	$r = shift;
+	my($buf,$len,$offset) = @_;
+	print "WRITE called, \$buf=$buf, \$len=$len, \$offset=$offset";
+    }
+
 =item PRINT this, LIST
 
 This method will be triggered every time the tied handle is printed to
@@ -654,15 +674,18 @@ passed to the printf function.
         print sprintf($fmt, @_)."\n";
     }
 
-=item READ this LIST
+=item READ this, LIST
 
 This method will be called when the handle is read from via the C<read>
 or C<sysread> functions.
 
     sub READ {
-	$r = shift;
-	my($buf,$len,$offset) = @_;
-	print "READ called, \$buf=$buf, \$len=$len, \$offset=$offset";
+	my $self = shift;
+	my $$bufref = \$_[0];
+	my(undef,$len,$offset) = @_;
+	print "READ called, \$buf=$bufref, \$len=$len, \$offset=$offset";
+	# add to $$bufref, set $len to number of characters read
+	$len;
     }
 
 =item READLINE this
@@ -670,7 +693,7 @@ or C<sysread> functions.
 This method will be called when the handle is read from via <HANDLE>.
 The method should return undef when there is no more data.
 
-    sub READLINE { $r = shift; "PRINT called $$r times\n"; }
+    sub READLINE { $r = shift; "READLINE called $$r times\n"; }
 
 =item GETC this
 
@@ -678,6 +701,13 @@ This method will be called when the C<getc> function is called.
 
     sub GETC { print "Don't GETC, Get Perl"; return "a"; }
 
+=item CLOSE this
+
+This method will be called when the handle is closed via the C<close>
+function.
+
+    sub CLOSE { print "CLOSE called.\n" }
+
 =item DESTROY this
 
 As with the other types of ties, this method will be called when the