"Lua is an extension programming language designed to support general procedural programming with data description facilities. It also offers good support for object-oriented programming, functional programming, and data-driven programming. Lua is intended to be used as a powerful, light-weight scripting language for any program that needs one." (from "Lua 5.1 Reference Manual" by Roberto Ierusalimschy, Luiz Henrique de Figueiredo, Waldemar Celes)
This module provides a BlitzMax interface to the Lua main and auxiliary APIs. It is almost complete, the only functions missing are those with variable argument lists (which are not yet supported by BlitzMax).
The axe.lua package also contains the full Lua 5.1.4 distribution. The Lua source code is completely integrated into the module, additional DLLs (or shared libraries, resp.) are no longer required.
Lua Documentation edit
The Lua Reference Manual is part of this distribution and may be directly visited from here:
Additional information can be found on the Lua web site; the Lua wiki contains further material about this module and related packages.
Introduction edit
The following description is not meant as a tutorial, but may still help you to start Lua programming within BlitzMax. More API-related information can be found in the Lua Reference Manual
Setting up a Lua VM edit
Running Lua scripts always require the instantiation of at least one Lua VM:
local LuaState:byte ptr = luaL_newstate()
The result of this instantiation is a pointer to a structure which contains the full state of the new VM and has to be passed as the first argument to almost any other Lua API function.
It is now time to "open" the intrinsic Lua libraries (note: these libraries are part of axe.lua now, external DLLs or shared libraries are not necessary):
luaL_openlibs(LuaState)
Always initialize the Lua VM by opening its libraries unless you really know what you are doing!
Usually, creating a single Lua state is sufficient, even further (Lua) threads share the basic Lua state (and its associated environment).
Shutting down a Lua VM edit
At the end, it's always a good idea to shut down the Lua VM
lua_close(LuaState)
The Lua interpreter has now been terminated and its state variable is no longer valid.
Accessing Lua Globals edit
The code
lua_pushstring(LuaState, "BMXString")
lua_setglobal (LuaState, "luaglobal")
defines a global Lua variable (called luaglobal) which contains a string (namely "BMXString").
Registering BlitzMax Functions edit
In order to access BlitzMax features from within a Lua script, it is necessary to implement suitable BlitzMax functions and register them in the Lua VM.
Such BlitzMax functions typically look as follows:
function BMXName:int (LuaState:Byte Ptr)
... ' handling of parameters passed from Lua (if required)
... ' actual function body
... ' passing results back to Lua (if required)
return 0 ' number of values returned to Lua
end function
Such a function is then registered using
lua_register(LuaState, "luaname", BMXName)
This command registers a BlitzMax function (called BMXName) with the (global) name luaname under Lua. Both names may be equal, but they do not have to.
Running Lua Scripts From Within BlitzMax edit
The code
local Result:int = luaL_loadString(LuaState,LuaScript)
if (Result <> 0) then
' ERROR!!!
lua_close(LuaState) ' just to be complete
end
end if
loads and compiles a (BlitzMax) string containing a LuaScript. The result (of compilation) is left on the (Lua) stack.
lua_getfield(LuaState, LUA_GLOBALSINDEX, "debug")' get global "debug"
lua_getfield(LuaState, -1, "traceback") ' get "debug.traceback"
lua_remove (LuaState, -2) ' remove "debug" table from stack
Result = lua_pcall(LuaState,1,-1,-1)' use "debug.traceback" as err.hdlr
if (Result <> 0) then
' ERROR
lua_close(LuaState) ' just to be complete
end
end if
actually evaluates the previously loaded script. The initially mentioned Lua commands just prepare for proper error messages should the Lua script fail.
Functions edit
Lua_atpanic edit
Function lua_atpanic:Byte Ptr (lua_state:Byte Ptr, panicf:Int(ls:Byte Ptr)
Description: see Lua Reference Manual
Lua_call edit
Function lua_call (lua_state:Byte Ptr, nargs:Int, nresults:Int)
Description: see Lua Reference Manual
Lua_checkstack edit
Function lua_checkstack:Int (lua_state:Byte Ptr, extra:Int)
Description: see Lua Reference Manual
Lua_close edit
Function lua_close (lua_state:Byte Ptr)
Description: see Lua Reference Manual
Lua_concat edit
Function lua_concat (lua_state:Byte Ptr, n:Int)
Description: see Lua Reference Manual
Lua_cpcall edit
Function lua_cpcall:Int (lua_state:Byte Ptr, func:Int(ls:Byte Ptr)
Description: see Lua Reference Manual
Lua_createtable edit
Function lua_createtable (lua_state:Byte Ptr, narr:Int, nrec:Int)
Description: see Lua Reference Manual
Lua_dump edit
Function lua_dump:Int (lua_state:Byte Ptr, writer:Int(ls:Byte Ptr,p:Byte Ptr,sz:Int,ud:Byte Ptr)
Description: see Lua Reference Manual
Lua_equal edit
Function lua_equal:Int (lua_state:Byte Ptr, index1:Int, index2:Int)
Description: see Lua Reference Manual
Lua_error edit
Function lua_error:Int (lua_state:Byte Ptr)
Description: see Lua Reference Manual
Lua_gc edit
Function lua_gc:Int (lua_state:Byte Ptr, what:Int, data:Int)
Description: see Lua Reference Manual
Lua_getallocf edit
Function lua_getallocf:Byte Ptr (lua_state:Byte Ptr, ud:Byte Ptr Ptr)
Description: see Lua Reference Manual
Lua_getfenv edit
Function lua_getfenv (lua_state:Byte Ptr, index:Int)
Description: see Lua Reference Manual
Lua_getfield edit
Function lua_getfield (lua_state:Byte Ptr, index:Int, k$z)
Description: see Lua Reference Manual
Lua_gethook edit
Function lua_gethook:Byte Ptr (lua_state:Byte Ptr)
Description: see Lua Reference Manual
Lua_gethookcount edit
Function lua_gethookcount:Int (lua_state:Byte Ptr)
Description: see Lua Reference Manual
Lua_gethookmask edit
Function lua_gethookmask:Int (lua_state:Byte Ptr)
Description: see Lua Reference Manual
Lua_getinfo edit
Function lua_getinfo:Int (lua_state:Byte Ptr, what$z, ar:lua_Debug Ptr)
Description: see Lua Reference Manual
Lua_getlocal edit
Function lua_getlocal$z (lua_state:Byte Ptr, ar:lua_Debug Ptr, n:Int)
Description: see Lua Reference Manual
Lua_getmetatable edit
Function lua_getmetatable:Int (lua_state:Byte Ptr, index:Int)
Description: see Lua Reference Manual
Lua_getstack edit
Function lua_getstack:Int (lua_state:Byte Ptr, level:Int, ar:lua_Debug Ptr)
Description: see Lua Reference Manual
Lua_gettable edit
Function lua_gettable (lua_state:Byte Ptr, index:Int)
Description: see Lua Reference Manual
Lua_gettop edit
Function lua_gettop:Int (lua_state:Byte Ptr)
Description: see Lua Reference Manual
Lua_getupvalue edit
Function lua_getupvalue$z (lua_state:Byte Ptr, funcindex:Int, n:Int)
Description: see Lua Reference Manual
Lua_insert edit
Function lua_insert (lua_state:Byte Ptr, index:Int)
Description: see Lua Reference Manual
Lua_iscfunction edit
Function lua_iscfunction:Int (lua_state:Byte Ptr, index:Int)
Description: see Lua Reference Manual
Lua_isnumber edit
Function lua_isnumber:Int (lua_state:Byte Ptr, index:Int)
Description: see Lua Reference Manual
Lua_isstring edit
Function lua_isstring:Int (lua_state:Byte Ptr, index:Int)
Description: see Lua Reference Manual
Lua_isuserdata edit
Function lua_isuserdata:Int (lua_state:Byte Ptr, index:Int)
Description: see Lua Reference Manual
Lua_lessthan edit
Function lua_lessthan:Int (lua_state:Byte Ptr, index1:Int, index2:Int)
Description: see Lua Reference Manual
Lua_load edit
Function lua_load:Int (lua_state:Byte Ptr, reader:Byte Ptr(ls:Byte Ptr,data:Byte Ptr,sz:Int Ptr)
Description: see Lua Reference Manual
Lua_newstate edit
Function lua_newstate:Byte Ptr (f:Byte Ptr(ud:Byte Ptr, p:Byte Ptr, osize:Int, nsize:Int)
Description: see Lua Reference Manual
Lua_newthread edit
Function lua_newthread:Byte Ptr (lua_state:Byte Ptr)
Description: see Lua Reference Manual
Lua_newuserdata edit
Function lua_newuserdata:Byte Ptr (lua_state:Byte Ptr, size:Int)
Description: see Lua Reference Manual
Lua_next edit
Function lua_next:Int (lua_state:Byte Ptr, index:Int)
Description: see Lua Reference Manual
Lua_objlen edit
Function lua_objlen:Int (lua_state:Byte Ptr, index:Int)
Description: see Lua Reference Manual
Lua_pcall edit
Function lua_pcall:Int (lua_state:Byte Ptr, nargs:Int, nresults:Int, errfunc:Int)
Description: see Lua Reference Manual
Lua_pushboolean edit
Function lua_pushboolean (lua_state:Byte Ptr, b:Int)
Description: see Lua Reference Manual
Lua_pushcclosure edit
Function lua_pushcclosure (lua_state:Byte Ptr, fn:Int(ls:Byte Ptr)
Description: see Lua Reference Manual
Lua_pushinteger edit
Function lua_pushinteger (lua_state:Byte Ptr, n:Int)
Description: see Lua Reference Manual
Lua_pushlightuserdata edit
Function lua_pushlightuserdata (lua_state:Byte Ptr, p:Byte Ptr)
Description: see Lua Reference Manual
Lua_pushlstring edit
Function lua_pushlstring (lua_state:Byte Ptr, s:Byte Ptr, size:Int)
Description: see Lua Reference Manual
Lua_pushnil edit
Function lua_pushnil (lua_state:Byte Ptr)
Description: see Lua Reference Manual
Lua_pushnumber edit
Function lua_pushnumber (lua_state:Byte Ptr, n:Double)
Description: see Lua Reference Manual
Lua_pushstring edit
Function lua_pushstring (lua_state:Byte Ptr, s$z)
Description: see Lua Reference Manual
Lua_pushthread edit
Function lua_pushthread:Int (lua_state:Byte Ptr)
Description: see Lua Reference Manual
Lua_pushvalue edit
Function lua_pushvalue (lua_state:Byte Ptr, index:Int)
Description: see Lua Reference Manual
Lua_rawequal edit
Function lua_rawequal:Int (lua_state:Byte Ptr, index1:Int, index2:Int)
Description: see Lua Reference Manual
Lua_rawget edit
Function lua_rawget (lua_state:Byte Ptr, index:Int)
Description: see Lua Reference Manual
Lua_rawgeti edit
Function lua_rawgeti (lua_state:Byte Ptr, index:Int, n:Int)
Description: see Lua Reference Manual
Lua_rawset edit
Function lua_rawset (lua_state:Byte Ptr, index:Int)
Description: see Lua Reference Manual
Lua_rawseti edit
Function lua_rawseti (lua_state:Byte Ptr, index:Int, n:Int)
Description: see Lua Reference Manual
Lua_remove edit
Function lua_remove (lua_state:Byte Ptr, index:Int)
Description: see Lua Reference Manual
Lua_replace edit
Function lua_replace (lua_state:Byte Ptr, index:Int)
Description: see Lua Reference Manual
Lua_resume edit
Function lua_resume:Int (lua_state:Byte Ptr, narg:Int)
Description: see Lua Reference Manual
Lua_setallocf edit
Function lua_setallocf (lua_state:Byte Ptr, f:Byte Ptr(ud:Byte Ptr, p:Byte Ptr, osize:Int, nsize:Int)
Description: see Lua Reference Manual
Lua_setfenv edit
Function lua_setfenv:Int (lua_state:Byte Ptr, index:Int)
Description: see Lua Reference Manual
Lua_setfield edit
Function lua_setfield (lua_state:Byte Ptr, index:Int, k$z)
Description: see Lua Reference Manual
Lua_sethook edit
Function lua_sethook:Int (lua_state:Byte Ptr, f(ls:Byte Ptr,ar:lua_Debug Ptr)
Description: see Lua Reference Manual
Lua_setlocal edit
Function lua_setlocal$z (lua_state:Byte Ptr, ar:lua_Debug Ptr, n:Int)
Description: see Lua Reference Manual
Lua_setmetatable edit
Function lua_setmetatable:Int (lua_state:Byte Ptr, index:Int)
Description: see Lua Reference Manual
Lua_settable edit
Function lua_settable (lua_state:Byte Ptr, index:Int)
Description: see Lua Reference Manual
Lua_settop edit
Function lua_settop (lua_state:Byte Ptr, index:Int)
Description: see Lua Reference Manual
Lua_setupvalue edit
Function lua_setupvalue$z (lua_state:Byte Ptr, funcindex:Int, n:Int)
Description: see Lua Reference Manual
Lua_status edit
Function lua_status:Int (lua_state:Byte Ptr)
Description: see Lua Reference Manual
Lua_toboolean edit
Function lua_toboolean:Int (lua_state:Byte Ptr, index:Int)
Description: see Lua Reference Manual
Lua_tocfunction edit
Function lua_tocfunction:Byte Ptr (lua_state:Byte Ptr, index:Int)
Description: see Lua Reference Manual
Lua_tointeger edit
Function lua_tointeger:Int (lua_state:Byte Ptr, index:Int)
Description: see Lua Reference Manual
Lua_tolstring edit
Function lua_tolstring:Byte Ptr (lua_state:Byte Ptr, index:Int, size:Int Ptr)
Description: see Lua Reference Manual
Lua_tonumber edit
Function lua_tonumber:Double (lua_state:Byte Ptr, index:Int)
Description: see Lua Reference Manual
Lua_topointer edit
Function lua_topointer:Byte Ptr (lua_state:Byte Ptr, index:Int)
Description: see Lua Reference Manual
Lua_tothread edit
Function lua_tothread:Byte Ptr (lua_state:Byte Ptr, index:Int)
Description: see Lua Reference Manual
Lua_touserdata edit
Function lua_touserdata:Byte Ptr (lua_state:Byte Ptr, index:Int)
Description: see Lua Reference Manual
Lua_type edit
Function lua_type:Int (lua_state:Byte Ptr, index:Int)
Description: see Lua Reference Manual
Lua_typename edit
Function lua_typename$z (lua_state:Byte Ptr, tp:Int)
Description: see Lua Reference Manual
Lua_xmove edit
Function lua_xmove (fromState:Byte Ptr, toState:Byte Ptr, n:Int)
Description: see Lua Reference Manual
Lua_yield edit
Function lua_yield:Int (lua_state:Byte Ptr, nresults:Int)
Description: see Lua Reference Manual
Lua_getglobal edit
Function lua_getglobal (lua_state:Byte Ptr, name:String)
Description: see Lua Reference Manual
Lua_isboolean edit
Function lua_isboolean:Int (lua_state:Byte Ptr, index:Int)
Description: see Lua Reference Manual
Lua_isfunction edit
Function lua_isfunction:Int (lua_state:Byte Ptr, index:Int)
Description: see Lua Reference Manual
Lua_islightuserdata edit
Function lua_islightuserdata:Int (lua_state:Byte Ptr, index:Int)
Description: see Lua Reference Manual
Lua_isnil edit
Function lua_isnil:Int (lua_state:Byte Ptr, index:Int)
Description: see Lua Reference Manual
Lua_isnone edit
Function lua_isnone:Int (lua_state:Byte Ptr, index:Int)
Description: see Lua Reference Manual
Lua_isnoneornil edit
Function lua_isnoneornil:Int (lua_state:Byte Ptr, index:Int)
Description: see Lua Reference Manual
Lua_istable edit
Function lua_istable:Int (lua_state:Byte Ptr, index:Int)
Description: see Lua Reference Manual
Lua_isthread edit
Function lua_isthread:Int (lua_state:Byte Ptr, index:Int)
Description: see Lua Reference Manual
Lua_newtable edit
Function lua_newtable (lua_state:Byte Ptr)
Description: see Lua Reference Manual
Lua_pop edit
Function lua_pop (lua_state:Byte Ptr, n:Int)
Description: see Lua Reference Manual
Lua_pushcfunction edit
Function lua_pushcfunction (lua_state:Byte Ptr, fn:Int(ls:Byte Ptr)
Description: see Lua Reference Manual
Lua_register edit
Function lua_register (lua_state:Byte Ptr, name:String, f:Int(ls:Byte Ptr)
Description: see Lua Reference Manual
Lua_setglobal edit
Function lua_setglobal (lua_state:Byte Ptr, name:String)
Description: see Lua Reference Manual
Lua_tostring edit
Function lua_tostring:String (lua_state:Byte Ptr, index:Int)
Description: see Lua Reference Manual
LuaL_addlstring edit
Function luaL_addlstring (B:Byte Ptr, s:Byte Ptr, l:Int)
Description: see Lua Reference Manual
LuaL_addsize edit
Function luaL_addsize (B:Byte Ptr, size:Int)
Description: see Lua Reference Manual
LuaL_addstring edit
Function luaL_addstring (B:Byte Ptr, s$z)
Description: see Lua Reference Manual
LuaL_addvalue edit
Function luaL_addvalue (B:Byte Ptr)
Description: see Lua Reference Manual
LuaL_argerror edit
Function luaL_argerror:Int (lua_state:Byte Ptr, narg:Int, extramsg$z)
Description: see Lua Reference Manual
LuaL_buffinit edit
Function luaL_buffinit (lua_state:Byte Ptr, B:Byte Ptr)
Description: see Lua Reference Manual
LuaL_callmeta edit
Function luaL_callmeta:Int (lua_state:Byte Ptr, obj:Int, e$z)
Description: see Lua Reference Manual
LuaL_checkany edit
Function luaL_checkany (lua_state:Byte Ptr, narg:Int)
Description: see Lua Reference Manual
LuaL_checkinteger edit
Function luaL_checkinteger:Int (lua_state:Byte Ptr, narg:Int)
Description: see Lua Reference Manual
LuaL_checklstring edit
Function luaL_checklstring:Byte Ptr (lua_state:Byte Ptr, narg:Int, size:Int Ptr)
Description: see Lua Reference Manual
LuaL_checknumber edit
Function luaL_checknumber:Double (lua_state:Byte Ptr, narg:Int)
Description: see Lua Reference Manual
LuaL_checkstack edit
Function luaL_checkstack (lua_state:Byte Ptr, sz:Int, msg$z)
Description: see Lua Reference Manual
LuaL_checktype edit
Function luaL_checktype (lua_state:Byte Ptr, narg:Int, t:Int)
Description: see Lua Reference Manual
LuaL_checkudata edit
Function luaL_checkudata:Byte Ptr (lua_state:Byte Ptr, narg:Int, tname$z)
Description: see Lua Reference Manual
LuaL_getmetafield edit
Function luaL_getmetafield:Int (lua_state:Byte Ptr, obj:Int, e$z)
Description: see Lua Reference Manual
LuaL_gsub edit
Function luaL_gsub$z (lua_state:Byte Ptr, s$z, p$z, r$z)
Description: see Lua Reference Manual
LuaL_loadbuffer edit
Function luaL_loadbuffer:Int (lua_state:Byte Ptr, buff:Byte Ptr, sz:Int, name$z)
Description: see Lua Reference Manual
LuaL_loadfile edit
Function luaL_loadfile:Int (lua_state:Byte Ptr, filename$z)
Description: see Lua Reference Manual
LuaL_loadstring edit
Function luaL_loadstring:Int (lua_state:Byte Ptr, s$z)
Description: see Lua Reference Manual
LuaL_newmetatable edit
Function luaL_newmetatable:Int (lua_state:Byte Ptr, tname$z)
Description: see Lua Reference Manual
LuaL_newstate edit
Function luaL_newstate:Byte Ptr ()
Description: see Lua Reference Manual
LuaL_openlibs edit
Function luaL_openlibs (lua_state:Byte Ptr)
Description: see Lua Reference Manual
LuaL_optinteger edit
Function luaL_optinteger:Int (lua_state:Byte Ptr, narg:Int, d:Int)
Description: see Lua Reference Manual
LuaL_optlstring edit
Function luaL_optlstring:Byte Ptr (lua_state:Byte Ptr, narg:Int, d$z, size:Int Ptr)
Description: see Lua Reference Manual
LuaL_optnumber edit
Function luaL_optnumber:Double (lua_state:Byte Ptr, narg:Int, d:Double)
Description: see Lua Reference Manual
LuaL_prepbuffer edit
Function luaL_prepbuffer:Byte Ptr (B:Byte Ptr)
Description: see Lua Reference Manual
LuaL_pushresult edit
Function luaL_pushresult (B:Byte Ptr)
Description: see Lua Reference Manual
LuaL_ref edit
Function luaL_ref:Int (lua_state:Byte Ptr, t:Int)
Description: see Lua Reference Manual
LuaL_register edit
Function luaL_register (lua_state:Byte Ptr, libname$z, l:lua_Reg Ptr)
Description: see Lua Reference Manual
LuaL_typerror edit
Function luaL_typerror:Int (lua_state:Byte Ptr, narg:Int, tname$z)
Description: see Lua Reference Manual
LuaL_unref edit
Function luaL_unref (lua_state:Byte Ptr, t:Int, ref:Int)
Description: see Lua Reference Manual
LuaL_where edit
Function luaL_where (lua_state:Byte Ptr, lvl:Int)
Description: see Lua Reference Manual
LuaL_addchar edit
Function luaL_addchar (B:Byte Ptr, c:String)
Description: see Lua Reference Manual
LuaL_argcheck edit
Function luaL_argcheck (lua_state:Byte Ptr, cond:Int, narg:Int, extramsg:String)
Description: see Lua Reference Manual
LuaL_checkint edit
Function luaL_checkint:Int (lua_state:Byte Ptr, narg:Int)
Description: see Lua Reference Manual
LuaL_checklong edit
Function luaL_checklong:Long (lua_state:Byte Ptr, narg:Int)
Description: see Lua Reference Manual
LuaL_checkstring edit
Function luaL_checkstring:String (lua_state:Byte Ptr, narg:Int)
Description: see Lua Reference Manual
LuaL_dofile edit
Function luaL_dofile:Int (lua_state:Byte Ptr, filename:String)
Description: see Lua Reference Manual
LuaL_dostring edit
Function luaL_dostring:Int (lua_state:Byte Ptr, str:String)
Description: see Lua Reference Manual
LuaL_getmetatable edit
Function luaL_getmetatable (lua_state:Byte Ptr, tname:String)
Description: see Lua Reference Manual
LuaL_optint edit
Function luaL_optint:Int (lua_state:Byte Ptr, narg:Int, d:Int)
Description: see Lua Reference Manual
LuaL_optlong edit
Function luaL_optlong:Long (lua_state:Byte Ptr, narg:Int, d:Long)
Description: see Lua Reference Manual
LuaL_optstring edit
Function luaL_optstring:String (lua_state:Byte Ptr, narg:Int, d:String)
Description: see Lua Reference Manual
LuaL_typename edit
Function luaL_typename:String (lua_state:Byte Ptr, idx:Int)
Description: see Lua Reference Manual