Lua C API

[Jim <djvaios@...>]

when looking at Lua's C API i wondered why many of the API functions
do not return a result where that would make sense and just return
"void" (i. e. nothing), for example:

lua_call()
lua_close()
lua_concat()
lua_copy()
lua_createtable()
...
lua_len()
...
lua_newtable()
...
lua_pop()
lua_push*()
...

here it might be useful to indicate whether the call succceeded by returning
a result (probably an int). this does not even break compatibility since that
new return value can be easily ignored and/or casted away via (void) where
it is not wanted/needed.

in the case of the lua_to*() functions i would suggest to also return a success
result (an int) and return the requested value via an output pointer parameter
provided by the caller, for example:

int lua_toboolean ( lua_State * L, int index, int * result ) ;

int lua_tointeger ( lua_State * L, int index, lua_Integer * result ) ;
^^^ indicates whether the call succeeded, i. e. if the value at the
given stack index
could get converted to an lua_Integer, the result is copied into the
output argument
pointer provided by the caller.

this way it is possible to tell if the lua_tointeger() call succeeded
and the given
(by index) stack position contained a zero or if the call failed.
that is clearly an advantage IMO.

further such functions could be added, eg

int lua_tounsigned ( lua_State * L, int index, lua_Unsigned * result ) ;

for lua_Unsigned or

int lua_convert2integer ( lua_State * L, int index, lua_Integer * result ) ;

that tries to convert the value at the given stack position to an
integer an so on.
they should be named differently to preserve compatibility and the original
API functions could be implemented in terms of the new ones.

Lua C functions:

int  cfunc ( lua_State * L ) ;

what do negative results mean here ?
do they indicate error situations ? are they used anywhere ?
why not

int cfunc ( lua_State * L, unsigned int * nres ) ;

instead ?

the int result indicates to the Lua interpreter whether the C function call
succeeded and in that case the second output pointer argument "nres"
contains the number of results on the stack (could be zero of course).

so certain return codes could indicate a specific outcome like so:

enum {
  LUA_OK,
  LUA_ERROR,
  LUA_POSIX_ERROR,
  ...
} ;

so as a simple example the result LUA_POSIX_ERROR could indicate to
the Lua interpreter that a syscall failed and that in this case if 0 <
nres holds
the value copied to the output parameter pointer is the corresponding errno
value (just a little example of what could be possible).

BTW:

in the case of

int luaL_argerror (lua_State *L, int arg, const char *extramsg) ;

it would be nice if this could be changed to work akin to

int luaL_error ( lua_State * L, const char * fmt, ... ) ;

(which it calls anyway). this would enable the caller to not only pass
one string
but use a fmt and supplied values to create more helpful argument
error messages.