Module bytereader

A ByteReader transforms Lua inputs adhering to a simple protocol into a bytes-count pair that other C and C++ APIs are able to safely consume.

The protocol goes as follows:

The object at index arg (in Lua state L) is examined.

If it happens to be a string, we can use its bytes and length directly.

Failing that, the object's metatable (if it has one) is queried for field __bytes. If no value is found, the object clearly does not honor the protocol, so we error out.

If __bytes is neither a light userdata nor a function, we have a garden-variety object and can use its bytes and length directly, as with strings.

When __bytes is a light userdata, it is assumed to point to a ByteReaderFunc struct, containing a reader function mGetBytes and a user-supplied context mContext. (The light userdata must also be present as a key in the Lua registry.) This is called as mGetBytes(L, reader, arg, mContext), where reader is our byte reader, whose mBytes and mCount members the function should supply. (See below how to handle errors.)

The object in the foregoing cases must be a full userdata.

The remaining possibility is that __bytes is a function, to be called as

object = func(object)

The process (i.e. is the object a string? if not, does it have a __bytes metafield? et al.) then recurses on this new object, using the final result.

When bytes are successfully found, the reader's mBytes member will point to them, with the byte count stored in mCount. If bReplace is true (the default), the final bytes object—either a string or full userdata—is moved into slot arg, overwriting the original object (this only matters in the __bytes-as-function case, since otherwise the object will already be in position).

Should an error happen along the way, mBytes will be NULL and an error message is pushed on the stack.

generated by LDoc 1.4.0