Patch for pod/perlpod.pod

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

diff --git a/pod/perltie.pod b/pod/perltie.pod
index 658425e..7c43141 100644 (file)
--- a/pod/perltie.pod
+++ b/pod/perltie.pod
@@ -33,13 +33,14 @@ In the tie() call, C<VARIABLE> is the name of the variable to be
 enchanted.  C<CLASSNAME> is the name of a class implementing objects of
 the correct type.  Any additional arguments in the C<LIST> are passed to
 the appropriate constructor method for that class--meaning TIESCALAR(),
-TIEARRAY(), or TIEHASH().  (Typically these are arguments such as might be
-passed to the dbminit() function of C.) The object returned by the "new"
-method is also returned by the tie() function, which would be useful if
-you wanted to access other methods in C<CLASSNAME>. (You don't actually
-have to return a reference to a right "type" (e.g. HASH or C<CLASSNAME>)
-so long as it's a properly blessed object.)  You can also retrieve
-a reference to the underlying object using the tied() function.
+TIEARRAY(), TIEHASH() or TIEHANDLE().  (Typically these are arguments
+such as might be passed to the dbminit() function of C.) The object
+returned by the "new" method is also returned by the tie() function,
+which would be useful if you wanted to access other methods in
+C<CLASSNAME>. (You don't actually have to return a reference to a right
+"type" (e.g. HASH or C<CLASSNAME>) so long as it's a properly blessed
+object.)  You can also retrieve a reference to the underlying object
+using the tied() function.
 
 Unlike dbmopen(), the tie() function will not C<use> or C<require> a module
 for you--you need to do that explicitly yourself.
@@ -159,7 +160,7 @@ argument--the new value the user is trying to assign.
 =item DESTROY this
 
 This method will be triggered when the tied variable needs to be destructed.
-As with other object classes, such a method is seldom ncessary, since Perl
+As with other object classes, such a method is seldom necessary, since Perl
 deallocates its moribund object's memory for you automatically--this isn't
 C++, you know.  We'll use a DESTROY method here for debugging purposes only.
 
@@ -273,7 +274,7 @@ there.  For example:
 =item DESTROY this
 
 This method will be triggered when the tied variable needs to be destructed.
-As with the sclar tie class, this is almost never needed in a
+As with the scalar tie class, this is almost never needed in a
 language that does its own garbage collection, so this time we'll
 just leave it out.
 
@@ -573,7 +574,7 @@ second argument which is the last key that had been accessed.  This is
 useful if you're carrying about ordering or calling the iterator from more
 than one sequence, or not really storing things in a hash anywhere.
 
-For our example, we our using a real hash so we'll just do the simple
+For our example, we're using a real hash so we'll just do the simple
 thing, but we'll have to indirect through the LIST field.
 
     sub NEXTKEY  {
@@ -608,7 +609,61 @@ use the each() function to iterate over such.  Example:
 
 =head2 Tying FileHandles
 
-This isn't implemented yet.  Sorry; maybe someday.
+This is partially implemented now.
+
+A class implementing a tied filehandle should define the following methods:
+TIEHANDLE, PRINT and/or READLINE, and possibly 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
+special way. See nvi and the Apache module for examples.
+
+In our example we're going to create a shouting handle.
+
+    package Shout;
+
+=over
+
+=item TIEHANDLE classname, LIST
+
+This is the constructor for the class.  That means it is expected to
+return a blessed reference of some sort. The reference can be used to
+hold some internal information. We won't use it in out example.
+
+    sub TIEHANDLE { print "<shout>\n"; my $i; bless \$i, shift }
+
+=item PRINT this, LIST
+
+This method will be triggered every time the tied handle is printed to.
+Beyond its self reference it also expects the list that was passed to
+the print function.
+
+    sub PRINT { $r = shift; $$r++; print join($,,map(uc($_),@_)),$\ }
+
+=item READLINE this
+
+This method will be called when the handle is read from. The method
+should return undef when there is no more data.
+
+    sub READLINE { $r = shift; "PRINT called $$r times\n"; }
+
+=item DESTROY this
+
+As with the other types of ties, this method will be called when the
+tied handle is about to be destroyed. This is useful for debugging and
+possibly cleaning up.
+
+    sub DESTROY { print "</shout>\n" }
+
+=back
+
+Here's how to use our little example:
+
+    tie(*FOO,'Shout');
+    print FOO "hello\n";
+    $a = 4; $b = 6;
+    print FOO $a, " plus ", $b, " equals ", $a + $b, "\n";
+    print <FOO>;
 
 =head1 SEE ALSO
 
@@ -632,3 +687,5 @@ source code to MLDBM.
 =head1 AUTHOR
 
 Tom Christiansen
+
+TIEHANDLE by Sven Verdoolaege E<lt>F<skimo@dns.ufsia.ac.be>E<gt>