[perl #84942] perltie.pod READLINE list context
authorKevin Ryde <user42@zip.com.au>
Sat, 26 Feb 2011 05:50:50 +0000 (21:50 -0800)
committerFather Chrysostomos <sprout@cpan.org>
Sat, 26 Feb 2011 05:58:15 +0000 (21:58 -0800)
In perltie.pod the handle READLINE says

    The method should return undef when there is no more data.

which made me think that's what it should always do, and didn't need to
pay attention to wantarray().

If I'm not mistaken in list context READLINE should return empty list
for no more data.  It'd be good if the docs noted that, and perhaps
cross referenced to perlfunc for the gory details of what readline
should do.

Maybe something like the following, unless someone can think of a better
contrivance for the sample.

pod/perltie.pod

index d23c667..7ef471d 100644 (file)
@@ -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<perlfunc/readline>, in scalar context it should return the
+next line, or C<undef> if no more data.  In list context it should
+return all remaining lines or an empty list if no more data.  The
+input record separator C<$/> (see L<perlvar>) is included in the
+strings, or C<$/> C<undef> 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>