Permalink
Browse files

[docs] Updated StringHandle.readall and FileHandle.readall docs

They read just the rest of the buffer if tell > 0. [GH #1084]
This is not what you would expect, but perl6 wanted it this way.
See GH #930 for the discussion.
  • Loading branch information...
1 parent 5b2f932 commit 5410a6da51419141b8012b9a15c38041f9606a4f @rurban rurban committed Jul 16, 2014
Showing with 12 additions and 5 deletions.
  1. +2 −0 ChangeLog
  2. +5 −3 src/pmc/filehandle.pmc
  3. +5 −2 src/pmc/stringhandle.pmc
View
2 ChangeLog
@@ -2,6 +2,8 @@
- Core
- Build
- Documentation
+ + Updated documentation for StringHandle.readall and FileHandle.readall, which
+ reads just the rest of the buffer if tell > 0. [GH #1084]
- Tests
- Community
View
8 src/pmc/filehandle.pmc
@@ -406,7 +406,7 @@ Read a line from the filehandle and return it in a string.
=item METHOD readall(STRING *name);
-Read the entire contents of a file named I<name> into a Parrot string. On a
+Read the contents of a file named I<name> into a Parrot string. On a
filehandle object that isn't opened yet, the path to a file can be passed to
C<readall> and it will open a filehandle on that file, read in the contents,
and close the filehandle.
@@ -416,12 +416,14 @@ and close the filehandle.
$S0 = pio.'readall'('the_file')
If the filehandle is already open, then no file path should be passed. The
-C<readall> method will read the contents of the file, and will not close the
-filehandle when finished.
+C<readall> method will read the rest of the contents of the file, and will
+not close the filehandle when finished.
pio = open 'the_file', 'r'
$S0 = pio.'readall'()
+To ensure readall semantics C<seek> to position 0 first.
+
=cut
*/
View
7 src/pmc/stringhandle.pmc
@@ -217,8 +217,11 @@ Check if the StringHandle is open.
=item METHOD readall(STRING *name);
-Read the entire contents of the StringHandle into a Parrot string. On a
-StringHandle object that isn't opened yet, returns an empty string.
+Read the rest of the contents of the StringHandle into a Parrot string.
+On a StringHandle object that isn't opened yet, returns an empty string.
+
+To ensure readall semantics seek to position 0, which needs to be done
+in this case by checking C<is_closed()> and reopening the StringHandle.
=cut

0 comments on commit 5410a6d

Please sign in to comment.