Commit b776cec188 missed these RMG steps when preparing Module::CoreList for 5.19.11

[perl5.git] / pod / perltie.pod

diff --git a/pod/perltie.pod b/pod/perltie.pod
index d23c667..a200acc 100644 (file)
--- a/pod/perltie.pod
+++ b/pod/perltie.pod
@@ -195,7 +195,8 @@ TIESCALAR classes are certainly possible.
 X<array, tying>
 
 A class implementing a tied ordinary array should define the following
-methods: TIEARRAY, FETCH, STORE, FETCHSIZE, STORESIZE and perhaps UNTIE and/or DESTROY.
+methods: TIEARRAY, FETCH, STORE, FETCHSIZE, STORESIZE, CLEAR
+and perhaps UNTIE and/or DESTROY.
 
 FETCHSIZE and STORESIZE are used to provide C<$#array> and
 equivalent C<scalar(@array)> access.
@@ -870,11 +871,10 @@ program, where output to STDOUT and STDERR may have to be redirected
 in some special way.  See nvi and the Apache module for examples.
 
 When tying a handle, the first argument to C<tie> should begin with an
-asterisk. So, if you are tying STDOUT, use C<*STDOUT>. If you have assigned
-it to a scalar variable, say C<$handle>, use C<*$handle>. C<tie $handle>
-works, too, but that is considered a bug and will be fixed in Perl 5.16. It
-is supposed to tie the scalar C<$handle>, not the handle inside it.
-C<tie $handle> emits a deprecation warning as of Perl 5.14.
+asterisk.  So, if you are tying STDOUT, use C<*STDOUT>.  If you have
+assigned it to a scalar variable, say C<$handle>, use C<*$handle>.
+C<tie $handle> ties the scalar variable C<$handle>, not the handle inside
+it.
 
 In our example we're going to create a shouting handle.
 
@@ -947,10 +947,25 @@ or C<sysread> functions.
 =item READLINE this
 X<READLINE>
 
-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; "READLINE called $$r times\n"; }
+This method is called when the handle is read via C<E<lt>HANDLEE<gt>>
+or C<readline HANDLE>.
+
+As per L<C<readline>|perlfunc/readline>, in scalar context it should return
+the next line, or C<undef> for no more data.  In list context it should
+return all remaining lines, or an empty list for no more data.  The strings
+returned should include the input record separator C<$/> (see L<perlvar>),
+unless it is C<undef> (which means "slurp" mode).
+
+    sub READLINE {
+      my $r = shift;
+      if (wantarray) {
+        return ("all remaining\n",
+                "lines up\n",
+                "to eof\n");
+      } else {
+        return "READLINE called " . ++$$r . " times\n";
+      }
+    }
 
 =item GETC this
 X<GETC>