About the Lua stack.

Lua communicates with C/C++ with the Lua Stack. If you're not familiar with the idea of stacks as data structures, there's a good wiki page on the subject.

Basically, the stack is an array. In lua, the convention is that low numbers are near the bottom of the stack, and high numbers near the top. So index 1 is always the bottom of the stack. Adding items to the stack is called pushing, since you're metaphorically pushing the stack down to make room for a new item. Similarly, removing an item from the top is called popping.

When Lua calls a function defined in C/C++, the stack consists of the function arguments provided in the Lua script, with the first argument being at index 1, and the Nth at index N. Each Lua-to-C[1] call gets a new stack, so you don't need to worry about what might have been left on the last one you saw. When the C function returns, the stack needs to contain any return values, with the first one being at index 1. (Yes, Lua can return more than one value). The last thing on the stack has to be the number of return values. Lua will work it out from there.

Going the other way, if C calls Lua, the first the function needs to be pushed on first, followed by the first argument, then the second and so on. When the Lua code returns, the return values are on the stack[2]. The stack used here belongs to the lua_State and may have other things on it. So you can't assume that return value 1 is at index 1 in the stack. (Lua doesn't believe in counting-from-zero BTW. It can be terribly confusing for C types like myself).

The only other thing we need to talk about is how to access stack entries. Let's consider lua_tostring. This function takes a value on the stack and returns it as a string (converting the value on the stack to a Lua string in the process, if you accidentally it an int, or something non-stringy). If you know the index in the stack, you can access it directly:

        string foo =  lua_tostring(L, 1);

will initialise foo with the string value at index one - the base of the stack. The trouble is, often you don't know the absolute index, but you do know where the value is relative to the top of the stack. In this case you can use a negative index, and Lua will count down from the stack top.

        string foo =  lua_tostring(L, -2);



That gets the second item from the top of the stack.

So, now we have all the bits to get at the error message in the previous post...

[1] C or C++ - writing C/C++ everywhere is getting to be a pain.

[2] It's not exactly the same going from Lua to C because lua_call/lua_pcall tells Lua how many return values it expects, so there's no need for a count. See the function documentation if you need full details.