file:read("*n") reference manual entry improvement

[Lorenzo Donati <lorenzodonatibz@...>]

Hi All!

In a recent comments exchange on Stack Overflow [1] an issue with the
use of io.read("*n") came up which is related also to this [2] lua-l post.

The problem is that when reading a number fails, the manual is not clear
about what happens to the underlying stream, i.e. that an unpredictable
number of characters may be consumed (even no characters). A C-savy user
can understand the fscanf( ... "%lf" ... ) implications if pointed to
the online source of read_number function in liolib.c, but the regular
Lua-the-language user is at a loss.

IMHO it would be good if the file:read entry in the manual could say a
couple of words about the issue (since "*n" format is the only format
susceptible to this problem). I mean something on the line (emphasis on
additions):

"Reads the file file, according to the given formats, which specify what
to read. For each format, the function returns a string (or a number)
with the characters read, or nil if it cannot read data with the
specified format. When called without formats, it uses a default format
that reads the next line (see below). _When using the "*n" format
and the read operation fails, an unspecified number (>= 0) of characters
from file may be consumed._"

Of course better wording and/or more precise description would be welcome.

Cheers!

-- Lorenzo


[1] http://stackoverflow.com/questions/18682584/looping-if-statement-in-lua
[2] http://lua-users.org/lists/lua-l/2007-07/msg00323.html


-- 
()  ascii ribbon campaign - against html e-mail
/\  www.asciiribbon.org   - against proprietary attachments