Lua C API

Fun with stacks

The API is used by host programs to communicate with Lua.

lua_State

lua_State is structure that keep the whole state of Lua and it is the first parameter to all functions besides lua_newstate.

Lua Stack

The way to pass data to and from lua is with the Lua Stack. It is a virtual stack and each time lua call C there is a new stack with the parameters from the call. The default size for the stack is 20 elements. To select a thing in the stack an index is used and it goes from 1 (the first item in

the stack) to n (the last or top item in the stack). The index can also be negative and -1 is then the last item and -n is the first item.

Registry

The registry is a table that can be used by any C code to store Lua values. Use pseudo-index LUA_REGISTRYINDEX to access it. Integer keys in the registry is used by the reference machanism (luaL_ref) so integers keys should not be used by host code. LUA_RIDX_GLOBALS points to the global table.

How To

Push data onto stack - lua_push*()

To put data onto the stack the push functions are used. It is one function for each type of data. It adds the item on the top of the stack.

Get data from the stack - lua_to*()

To get data from the stack the to functions are used. They take the index in the stack to get the data from and then returns a value.

To check the type of a item in stack - lua_type / lua_is*()

To check the type at an index in the stack use lua_type. It is also possible to check for a specific type at an index by using the lua_is* functions.

Calling Lua Functions from C

To call a lua function the steps below is done.

Getting The Function

The first step is to get the function from lua and putting it onto the stack.

Push arguments

Push all arguments to the stack in direct order, the first argument is pushed first.

Call the function

Use lua_call or lua_pcall to run the function. They take the number of arguments you send in to the function and the maximum number of return values.

Get the return values

The function and the parameters will be removed from the stack by the call. The return values of the function will have been pushed onto the stack in direct order.

Calling C Functions from Lua

Lua can only call functions in the form of the Lua_CFunction. It's a function that takes a lua_State* that contain the parameters of the call and it return an int with the number of return values put into the stack.

Create the function to be called

Lua can only call C functions that fit the lua_CFunction. It is a function that takes a lua_State* as a single parameter and returns and int.

Register the function in lua

To be able to call the function from lua one need to put it somewhere where lua can call it. The simple way is to put it into a global variable with lua_register(). It takes the name and the function.

Get the arguments

The argument to the function will be in direct order. So the first argument is att index 1 in the stack and lua_gettop returns the number of arguments.

Push back the return values

Push the values to return on the stack in direct order. Then return the number of them as the return value in the C function. Other values in the stack will be discarded by Lua.