"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
editThe 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
editThe 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
editRunning 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
editAt 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
editThe 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
editIn 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
editThe 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
editLua_atpanic
editFunction lua_atpanic:Byte Ptr (lua_state:Byte Ptr, panicf:Int(ls:Byte Ptr)
Description: see Lua Reference Manual
Lua_call
editFunction lua_call (lua_state:Byte Ptr, nargs:Int, nresults:Int)
Description: see Lua Reference Manual
Lua_checkstack
editFunction lua_checkstack:Int (lua_state:Byte Ptr, extra:Int)
Description: see Lua Reference Manual
Lua_close
editFunction lua_close (lua_state:Byte Ptr)
Description: see Lua Reference Manual
Lua_concat
editFunction lua_concat (lua_state:Byte Ptr, n:Int)
Description: see Lua Reference Manual
Lua_cpcall
editFunction lua_cpcall:Int (lua_state:Byte Ptr, func:Int(ls:Byte Ptr)
Description: see Lua Reference Manual
Lua_createtable
editFunction lua_createtable (lua_state:Byte Ptr, narr:Int, nrec:Int)
Description: see Lua Reference Manual
Lua_dump
editFunction 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
editFunction lua_equal:Int (lua_state:Byte Ptr, index1:Int, index2:Int)
Description: see Lua Reference Manual
Lua_error
editFunction lua_error:Int (lua_state:Byte Ptr)
Description: see Lua Reference Manual
Lua_gc
editFunction lua_gc:Int (lua_state:Byte Ptr, what:Int, data:Int)
Description: see Lua Reference Manual
Lua_getallocf
editFunction lua_getallocf:Byte Ptr (lua_state:Byte Ptr, ud:Byte Ptr Ptr)
Description: see Lua Reference Manual
Lua_getfenv
editFunction lua_getfenv (lua_state:Byte Ptr, index:Int)
Description: see Lua Reference Manual
Lua_getfield
editFunction lua_getfield (lua_state:Byte Ptr, index:Int, k$z)
Description: see Lua Reference Manual
Lua_gethook
editFunction lua_gethook:Byte Ptr (lua_state:Byte Ptr)
Description: see Lua Reference Manual
Lua_gethookcount
editFunction lua_gethookcount:Int (lua_state:Byte Ptr)
Description: see Lua Reference Manual
Lua_gethookmask
editFunction lua_gethookmask:Int (lua_state:Byte Ptr)
Description: see Lua Reference Manual
Lua_getinfo
editFunction lua_getinfo:Int (lua_state:Byte Ptr, what$z, ar:lua_Debug Ptr)
Description: see Lua Reference Manual
Lua_getlocal
editFunction lua_getlocal$z (lua_state:Byte Ptr, ar:lua_Debug Ptr, n:Int)
Description: see Lua Reference Manual
Lua_getmetatable
editFunction lua_getmetatable:Int (lua_state:Byte Ptr, index:Int)
Description: see Lua Reference Manual
Lua_getstack
editFunction lua_getstack:Int (lua_state:Byte Ptr, level:Int, ar:lua_Debug Ptr)
Description: see Lua Reference Manual
Lua_gettable
editFunction lua_gettable (lua_state:Byte Ptr, index:Int)
Description: see Lua Reference Manual
Lua_gettop
editFunction lua_gettop:Int (lua_state:Byte Ptr)
Description: see Lua Reference Manual
Lua_getupvalue
editFunction lua_getupvalue$z (lua_state:Byte Ptr, funcindex:Int, n:Int)
Description: see Lua Reference Manual
Lua_insert
editFunction lua_insert (lua_state:Byte Ptr, index:Int)
Description: see Lua Reference Manual
Lua_iscfunction
editFunction lua_iscfunction:Int (lua_state:Byte Ptr, index:Int)
Description: see Lua Reference Manual
Lua_isnumber
editFunction lua_isnumber:Int (lua_state:Byte Ptr, index:Int)
Description: see Lua Reference Manual
Lua_isstring
editFunction lua_isstring:Int (lua_state:Byte Ptr, index:Int)
Description: see Lua Reference Manual
Lua_isuserdata
editFunction lua_isuserdata:Int (lua_state:Byte Ptr, index:Int)
Description: see Lua Reference Manual
Lua_lessthan
editFunction lua_lessthan:Int (lua_state:Byte Ptr, index1:Int, index2:Int)
Description: see Lua Reference Manual
Lua_load
editFunction 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
editFunction lua_newstate:Byte Ptr (f:Byte Ptr(ud:Byte Ptr, p:Byte Ptr, osize:Int, nsize:Int)
Description: see Lua Reference Manual
Lua_newthread
editFunction lua_newthread:Byte Ptr (lua_state:Byte Ptr)
Description: see Lua Reference Manual
Lua_newuserdata
editFunction lua_newuserdata:Byte Ptr (lua_state:Byte Ptr, size:Int)
Description: see Lua Reference Manual
Lua_next
editFunction lua_next:Int (lua_state:Byte Ptr, index:Int)
Description: see Lua Reference Manual
Lua_objlen
editFunction lua_objlen:Int (lua_state:Byte Ptr, index:Int)
Description: see Lua Reference Manual
Lua_pcall
editFunction lua_pcall:Int (lua_state:Byte Ptr, nargs:Int, nresults:Int, errfunc:Int)
Description: see Lua Reference Manual
Lua_pushboolean
editFunction lua_pushboolean (lua_state:Byte Ptr, b:Int)
Description: see Lua Reference Manual
Lua_pushcclosure
editFunction lua_pushcclosure (lua_state:Byte Ptr, fn:Int(ls:Byte Ptr)
Description: see Lua Reference Manual
Lua_pushinteger
editFunction lua_pushinteger (lua_state:Byte Ptr, n:Int)
Description: see Lua Reference Manual
Lua_pushlightuserdata
editFunction lua_pushlightuserdata (lua_state:Byte Ptr, p:Byte Ptr)
Description: see Lua Reference Manual
Lua_pushlstring
editFunction lua_pushlstring (lua_state:Byte Ptr, s:Byte Ptr, size:Int)
Description: see Lua Reference Manual
Lua_pushnil
editFunction lua_pushnil (lua_state:Byte Ptr)
Description: see Lua Reference Manual
Lua_pushnumber
editFunction lua_pushnumber (lua_state:Byte Ptr, n:Double)
Description: see Lua Reference Manual
Lua_pushstring
editFunction lua_pushstring (lua_state:Byte Ptr, s$z)
Description: see Lua Reference Manual
Lua_pushthread
editFunction lua_pushthread:Int (lua_state:Byte Ptr)
Description: see Lua Reference Manual
Lua_pushvalue
editFunction lua_pushvalue (lua_state:Byte Ptr, index:Int)
Description: see Lua Reference Manual
Lua_rawequal
editFunction lua_rawequal:Int (lua_state:Byte Ptr, index1:Int, index2:Int)
Description: see Lua Reference Manual
Lua_rawget
editFunction lua_rawget (lua_state:Byte Ptr, index:Int)
Description: see Lua Reference Manual
Lua_rawgeti
editFunction lua_rawgeti (lua_state:Byte Ptr, index:Int, n:Int)
Description: see Lua Reference Manual
Lua_rawset
editFunction lua_rawset (lua_state:Byte Ptr, index:Int)
Description: see Lua Reference Manual
Lua_rawseti
editFunction lua_rawseti (lua_state:Byte Ptr, index:Int, n:Int)
Description: see Lua Reference Manual
Lua_remove
editFunction lua_remove (lua_state:Byte Ptr, index:Int)
Description: see Lua Reference Manual
Lua_replace
editFunction lua_replace (lua_state:Byte Ptr, index:Int)
Description: see Lua Reference Manual
Lua_resume
editFunction lua_resume:Int (lua_state:Byte Ptr, narg:Int)
Description: see Lua Reference Manual
Lua_setallocf
editFunction 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
editFunction lua_setfenv:Int (lua_state:Byte Ptr, index:Int)
Description: see Lua Reference Manual
Lua_setfield
editFunction lua_setfield (lua_state:Byte Ptr, index:Int, k$z)
Description: see Lua Reference Manual
Lua_sethook
editFunction lua_sethook:Int (lua_state:Byte Ptr, f(ls:Byte Ptr,ar:lua_Debug Ptr)
Description: see Lua Reference Manual
Lua_setlocal
editFunction lua_setlocal$z (lua_state:Byte Ptr, ar:lua_Debug Ptr, n:Int)
Description: see Lua Reference Manual
Lua_setmetatable
editFunction lua_setmetatable:Int (lua_state:Byte Ptr, index:Int)
Description: see Lua Reference Manual
Lua_settable
editFunction lua_settable (lua_state:Byte Ptr, index:Int)
Description: see Lua Reference Manual
Lua_settop
editFunction lua_settop (lua_state:Byte Ptr, index:Int)
Description: see Lua Reference Manual
Lua_setupvalue
editFunction lua_setupvalue$z (lua_state:Byte Ptr, funcindex:Int, n:Int)
Description: see Lua Reference Manual
Lua_status
editFunction lua_status:Int (lua_state:Byte Ptr)
Description: see Lua Reference Manual
Lua_toboolean
editFunction lua_toboolean:Int (lua_state:Byte Ptr, index:Int)
Description: see Lua Reference Manual
Lua_tocfunction
editFunction lua_tocfunction:Byte Ptr (lua_state:Byte Ptr, index:Int)
Description: see Lua Reference Manual
Lua_tointeger
editFunction lua_tointeger:Int (lua_state:Byte Ptr, index:Int)
Description: see Lua Reference Manual
Lua_tolstring
editFunction lua_tolstring:Byte Ptr (lua_state:Byte Ptr, index:Int, size:Int Ptr)
Description: see Lua Reference Manual
Lua_tonumber
editFunction lua_tonumber:Double (lua_state:Byte Ptr, index:Int)
Description: see Lua Reference Manual
Lua_topointer
editFunction lua_topointer:Byte Ptr (lua_state:Byte Ptr, index:Int)
Description: see Lua Reference Manual
Lua_tothread
editFunction lua_tothread:Byte Ptr (lua_state:Byte Ptr, index:Int)
Description: see Lua Reference Manual
Lua_touserdata
editFunction lua_touserdata:Byte Ptr (lua_state:Byte Ptr, index:Int)
Description: see Lua Reference Manual
Lua_type
editFunction lua_type:Int (lua_state:Byte Ptr, index:Int)
Description: see Lua Reference Manual
Lua_typename
editFunction lua_typename$z (lua_state:Byte Ptr, tp:Int)
Description: see Lua Reference Manual
Lua_xmove
editFunction lua_xmove (fromState:Byte Ptr, toState:Byte Ptr, n:Int)
Description: see Lua Reference Manual
Lua_yield
editFunction lua_yield:Int (lua_state:Byte Ptr, nresults:Int)
Description: see Lua Reference Manual
Lua_getglobal
editFunction lua_getglobal (lua_state:Byte Ptr, name:String)
Description: see Lua Reference Manual
Lua_isboolean
editFunction lua_isboolean:Int (lua_state:Byte Ptr, index:Int)
Description: see Lua Reference Manual
Lua_isfunction
editFunction lua_isfunction:Int (lua_state:Byte Ptr, index:Int)
Description: see Lua Reference Manual
Lua_islightuserdata
editFunction lua_islightuserdata:Int (lua_state:Byte Ptr, index:Int)
Description: see Lua Reference Manual
Lua_isnil
editFunction lua_isnil:Int (lua_state:Byte Ptr, index:Int)
Description: see Lua Reference Manual
Lua_isnone
editFunction lua_isnone:Int (lua_state:Byte Ptr, index:Int)
Description: see Lua Reference Manual
Lua_isnoneornil
editFunction lua_isnoneornil:Int (lua_state:Byte Ptr, index:Int)
Description: see Lua Reference Manual
Lua_istable
editFunction lua_istable:Int (lua_state:Byte Ptr, index:Int)
Description: see Lua Reference Manual
Lua_isthread
editFunction lua_isthread:Int (lua_state:Byte Ptr, index:Int)
Description: see Lua Reference Manual
Lua_newtable
editFunction lua_newtable (lua_state:Byte Ptr)
Description: see Lua Reference Manual
Lua_pop
editFunction lua_pop (lua_state:Byte Ptr, n:Int)
Description: see Lua Reference Manual
Lua_pushcfunction
editFunction lua_pushcfunction (lua_state:Byte Ptr, fn:Int(ls:Byte Ptr)
Description: see Lua Reference Manual
Lua_register
editFunction lua_register (lua_state:Byte Ptr, name:String, f:Int(ls:Byte Ptr)
Description: see Lua Reference Manual
Lua_setglobal
editFunction lua_setglobal (lua_state:Byte Ptr, name:String)
Description: see Lua Reference Manual
Lua_tostring
editFunction lua_tostring:String (lua_state:Byte Ptr, index:Int)
Description: see Lua Reference Manual
LuaL_addlstring
editFunction luaL_addlstring (B:Byte Ptr, s:Byte Ptr, l:Int)
Description: see Lua Reference Manual
LuaL_addsize
editFunction luaL_addsize (B:Byte Ptr, size:Int)
Description: see Lua Reference Manual
LuaL_addstring
editFunction luaL_addstring (B:Byte Ptr, s$z)
Description: see Lua Reference Manual
LuaL_addvalue
editFunction luaL_addvalue (B:Byte Ptr)
Description: see Lua Reference Manual
LuaL_argerror
editFunction luaL_argerror:Int (lua_state:Byte Ptr, narg:Int, extramsg$z)
Description: see Lua Reference Manual
LuaL_buffinit
editFunction luaL_buffinit (lua_state:Byte Ptr, B:Byte Ptr)
Description: see Lua Reference Manual
LuaL_callmeta
editFunction luaL_callmeta:Int (lua_state:Byte Ptr, obj:Int, e$z)
Description: see Lua Reference Manual
LuaL_checkany
editFunction luaL_checkany (lua_state:Byte Ptr, narg:Int)
Description: see Lua Reference Manual
LuaL_checkinteger
editFunction luaL_checkinteger:Int (lua_state:Byte Ptr, narg:Int)
Description: see Lua Reference Manual
LuaL_checklstring
editFunction luaL_checklstring:Byte Ptr (lua_state:Byte Ptr, narg:Int, size:Int Ptr)
Description: see Lua Reference Manual
LuaL_checknumber
editFunction luaL_checknumber:Double (lua_state:Byte Ptr, narg:Int)
Description: see Lua Reference Manual
LuaL_checkstack
editFunction luaL_checkstack (lua_state:Byte Ptr, sz:Int, msg$z)
Description: see Lua Reference Manual
LuaL_checktype
editFunction luaL_checktype (lua_state:Byte Ptr, narg:Int, t:Int)
Description: see Lua Reference Manual
LuaL_checkudata
editFunction luaL_checkudata:Byte Ptr (lua_state:Byte Ptr, narg:Int, tname$z)
Description: see Lua Reference Manual
LuaL_getmetafield
editFunction luaL_getmetafield:Int (lua_state:Byte Ptr, obj:Int, e$z)
Description: see Lua Reference Manual
LuaL_gsub
editFunction luaL_gsub$z (lua_state:Byte Ptr, s$z, p$z, r$z)
Description: see Lua Reference Manual
LuaL_loadbuffer
editFunction luaL_loadbuffer:Int (lua_state:Byte Ptr, buff:Byte Ptr, sz:Int, name$z)
Description: see Lua Reference Manual
LuaL_loadfile
editFunction luaL_loadfile:Int (lua_state:Byte Ptr, filename$z)
Description: see Lua Reference Manual
LuaL_loadstring
editFunction luaL_loadstring:Int (lua_state:Byte Ptr, s$z)
Description: see Lua Reference Manual
LuaL_newmetatable
editFunction luaL_newmetatable:Int (lua_state:Byte Ptr, tname$z)
Description: see Lua Reference Manual
LuaL_newstate
editFunction luaL_newstate:Byte Ptr ()
Description: see Lua Reference Manual
LuaL_openlibs
editFunction luaL_openlibs (lua_state:Byte Ptr)
Description: see Lua Reference Manual
LuaL_optinteger
editFunction luaL_optinteger:Int (lua_state:Byte Ptr, narg:Int, d:Int)
Description: see Lua Reference Manual
LuaL_optlstring
editFunction luaL_optlstring:Byte Ptr (lua_state:Byte Ptr, narg:Int, d$z, size:Int Ptr)
Description: see Lua Reference Manual
LuaL_optnumber
editFunction luaL_optnumber:Double (lua_state:Byte Ptr, narg:Int, d:Double)
Description: see Lua Reference Manual
LuaL_prepbuffer
editFunction luaL_prepbuffer:Byte Ptr (B:Byte Ptr)
Description: see Lua Reference Manual
LuaL_pushresult
editFunction luaL_pushresult (B:Byte Ptr)
Description: see Lua Reference Manual
LuaL_ref
editFunction luaL_ref:Int (lua_state:Byte Ptr, t:Int)
Description: see Lua Reference Manual
LuaL_register
editFunction luaL_register (lua_state:Byte Ptr, libname$z, l:lua_Reg Ptr)
Description: see Lua Reference Manual
LuaL_typerror
editFunction luaL_typerror:Int (lua_state:Byte Ptr, narg:Int, tname$z)
Description: see Lua Reference Manual
LuaL_unref
editFunction luaL_unref (lua_state:Byte Ptr, t:Int, ref:Int)
Description: see Lua Reference Manual
LuaL_where
editFunction luaL_where (lua_state:Byte Ptr, lvl:Int)
Description: see Lua Reference Manual
LuaL_addchar
editFunction luaL_addchar (B:Byte Ptr, c:String)
Description: see Lua Reference Manual
LuaL_argcheck
editFunction luaL_argcheck (lua_state:Byte Ptr, cond:Int, narg:Int, extramsg:String)
Description: see Lua Reference Manual
LuaL_checkint
editFunction luaL_checkint:Int (lua_state:Byte Ptr, narg:Int)
Description: see Lua Reference Manual
LuaL_checklong
editFunction luaL_checklong:Long (lua_state:Byte Ptr, narg:Int)
Description: see Lua Reference Manual
LuaL_checkstring
editFunction luaL_checkstring:String (lua_state:Byte Ptr, narg:Int)
Description: see Lua Reference Manual
LuaL_dofile
editFunction luaL_dofile:Int (lua_state:Byte Ptr, filename:String)
Description: see Lua Reference Manual
LuaL_dostring
editFunction luaL_dostring:Int (lua_state:Byte Ptr, str:String)
Description: see Lua Reference Manual
LuaL_getmetatable
editFunction luaL_getmetatable (lua_state:Byte Ptr, tname:String)
Description: see Lua Reference Manual
LuaL_optint
editFunction luaL_optint:Int (lua_state:Byte Ptr, narg:Int, d:Int)
Description: see Lua Reference Manual
LuaL_optlong
editFunction luaL_optlong:Long (lua_state:Byte Ptr, narg:Int, d:Long)
Description: see Lua Reference Manual
LuaL_optstring
editFunction luaL_optstring:String (lua_state:Byte Ptr, narg:Int, d:String)
Description: see Lua Reference Manual
LuaL_typename
editFunction luaL_typename:String (lua_state:Byte Ptr, idx:Int)
Description: see Lua Reference Manual