Re: data, err = f() idiom

[Jerome Vuarand <jerome.vuarand@...>]

2012/1/19 Jorge <xxopxe@gmail.com>:
> When writing:
>
> local data, err = f()
>
> what is the error condition, data being nil, or err being not nil?
>
> Is returning data AND a error frowned upon? Example: your f() is
> instructed to return data in chunks of N bytes. But when the last chunk
> is being read, the connection (socket, whatever) closes and f has less
> than N bytes. An API that returns "incompletedata, 'closed'" is well
> regarded?

The idiom is to be used with assert, like that:

local data,status = assert(f())

That is, when an error occured a false value (nil or false) should be
returned followed by an error message. In that case assert won't
return, that means that in the line above status is only set if data
is a true value (not nil and not false). Now it's up to you to decide
whether reading past the end of the stream is an error or not. There
are two important examples that read streams in common Lua libraries.

The first is the file:read function from the standard io library: it
doesn't use that idiom. When it return nil there is no second return
value, and the nil itself indicates end of file. Other read errors are
not reported.

The second is the tcp{client}:receive function from LuaSocket, which
uses the idiom. It returns nil as the first return value when trying
to read past the end of stream, followed by "closed", followed by the
partial result. So you can use assert if you expect to read the total
number of bytes you requested and don't care about partial results
(because assert will discard them), or you can use custom error
handling, for example:

local bytes,err,partial = socket:receive(32)
if not bytes then
    if err=='closed' then
        bytes = partial -- less than 32 bytes is ok
    else
        error(err)
    end
end