Possible documentation improvement on Lua 5.1 Reference Manual, lua_call()

[Steve Litt <slitt@...>]

Hi all,

I think I discovered a possible improvement to the documentation in the Lua 
5.1 Reference Manual's description of lua_call() regarding calling of a 
specific function in a Lua script. 

http://www.lua.org/manual/5.1/manual.html#lua_call

For a newbie (me, for instance), I don't think this documentation is clear 
enough about what you use for the nargs argument to lua_call() and therefore 
lua_pcall. At one point it says:

"Finally you call lua_call; nargs is the number of arguments that you pushed 
onto the stack."

While this is technically correct, the newbie might interpret this as the 
number of arguments taken by the Lua function. It isn't. It's that number of 
arguments plus one more that's used by the function name.

So if you interpret nargs as the number of args required by the Lua function 
and do this:

    lua_getglobal(L, "tellme");
    if (lua_pcall(L, 0, 0, 0)) 
	bail(L, "lua_pcall() failed"); 

You get this at runtime:
=================
slitt@mydesk:~$ ./callfunc
In C, calling Lua

FATAL ERROR:
  lua_pcall() failed: attempt to call a nil value

slitt@mydesk:~$
=================

Only if you read VERY carefully and concentrate on the documentation's saying 
"All arguments and the function value are popped from the stack when the 
function is called" do you get the idea that maybe nargs includes the pushed 
function name as well as the args required by the Lua function. In that case 
you do this:

    lua_getglobal(L, "tellme");
    if (lua_pcall(L, 1, 0, 0)) 
	bail(L, "lua_pcall() failed"); 

And succeed:
=================
slitt@mydesk:~$ ./callfunc
In C, calling Lua
This is coming from lua.tellme.
Back in C again
slitt@mydesk:~$
=================

My suggestion is that just to help newbies, a strongly worded sentence be 
added to the lua_call() doc in the manual saying that IF you push a function 
name, that adds to nargs, and for instance, if the Lua function takes no 
arguments but you push the function name via lua_getglobal() or something 
similar, nargs is 1, not 0.

By the way, this C interface is entirely too cool. I love it. And I'm not 
sure, but I think there may be an interface to Lazarus or Free Pascal, which 
would solve A LOT of problems for me.

Thanks

SteveT

Steve Litt
Recession Relief Package
http://www.recession-relief.US
Twitter: http://www.twitter.com/stevelitt