BlitzMax/Modules/Other/Lua Core

"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 DocumentationEdit

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.

IntroductionEdit

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 VMEdit

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 VMEdit

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 GlobalsEdit

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 FunctionsEdit

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 BlitzMaxEdit

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.

FunctionsEdit

Lua_atpanicEdit

Function lua_atpanic:Byte Ptr (lua_state:Byte Ptr, panicf:Int(ls:Byte Ptr)

Description: see Lua Reference Manual

Lua_callEdit

Function lua_call (lua_state:Byte Ptr, nargs:Int, nresults:Int)

Description: see Lua Reference Manual

Lua_checkstackEdit

Function lua_checkstack:Int (lua_state:Byte Ptr, extra:Int)

Description: see Lua Reference Manual

Lua_closeEdit

Function lua_close (lua_state:Byte Ptr)

Description: see Lua Reference Manual

Lua_concatEdit

Function lua_concat (lua_state:Byte Ptr, n:Int)

Description: see Lua Reference Manual

Lua_cpcallEdit

Function lua_cpcall:Int (lua_state:Byte Ptr, func:Int(ls:Byte Ptr)

Description: see Lua Reference Manual

Lua_createtableEdit

Function lua_createtable (lua_state:Byte Ptr, narr:Int, nrec:Int)

Description: see Lua Reference Manual

Lua_dumpEdit

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_equalEdit

Function lua_equal:Int (lua_state:Byte Ptr, index1:Int, index2:Int)

Description: see Lua Reference Manual

Lua_errorEdit

Function lua_error:Int (lua_state:Byte Ptr)

Description: see Lua Reference Manual

Lua_gcEdit

Function lua_gc:Int (lua_state:Byte Ptr, what:Int, data:Int)

Description: see Lua Reference Manual

Lua_getallocfEdit

Function lua_getallocf:Byte Ptr (lua_state:Byte Ptr, ud:Byte Ptr Ptr)

Description: see Lua Reference Manual

Lua_getfenvEdit

Function lua_getfenv (lua_state:Byte Ptr, index:Int)

Description: see Lua Reference Manual

Lua_getfieldEdit

Function lua_getfield (lua_state:Byte Ptr, index:Int, k$z)

Description: see Lua Reference Manual

Lua_gethookEdit

Function lua_gethook:Byte Ptr (lua_state:Byte Ptr)

Description: see Lua Reference Manual

Lua_gethookcountEdit

Function lua_gethookcount:Int (lua_state:Byte Ptr)

Description: see Lua Reference Manual

Lua_gethookmaskEdit

Function lua_gethookmask:Int (lua_state:Byte Ptr)

Description: see Lua Reference Manual

Lua_getinfoEdit

Function lua_getinfo:Int (lua_state:Byte Ptr, what$z, ar:lua_Debug Ptr)

Description: see Lua Reference Manual

Lua_getlocalEdit

Function lua_getlocal$z (lua_state:Byte Ptr, ar:lua_Debug Ptr, n:Int)

Description: see Lua Reference Manual

Lua_getmetatableEdit

Function lua_getmetatable:Int (lua_state:Byte Ptr, index:Int)

Description: see Lua Reference Manual

Lua_getstackEdit

Function lua_getstack:Int (lua_state:Byte Ptr, level:Int, ar:lua_Debug Ptr)

Description: see Lua Reference Manual

Lua_gettableEdit

Function lua_gettable (lua_state:Byte Ptr, index:Int)

Description: see Lua Reference Manual

Lua_gettopEdit

Function lua_gettop:Int (lua_state:Byte Ptr)

Description: see Lua Reference Manual

Lua_getupvalueEdit

Function lua_getupvalue$z (lua_state:Byte Ptr, funcindex:Int, n:Int)

Description: see Lua Reference Manual

Lua_insertEdit

Function lua_insert (lua_state:Byte Ptr, index:Int)

Description: see Lua Reference Manual

Lua_iscfunctionEdit

Function lua_iscfunction:Int (lua_state:Byte Ptr, index:Int)

Description: see Lua Reference Manual

Lua_isnumberEdit

Function lua_isnumber:Int (lua_state:Byte Ptr, index:Int)

Description: see Lua Reference Manual

Lua_isstringEdit

Function lua_isstring:Int (lua_state:Byte Ptr, index:Int)

Description: see Lua Reference Manual

Lua_isuserdataEdit

Function lua_isuserdata:Int (lua_state:Byte Ptr, index:Int)

Description: see Lua Reference Manual

Lua_lessthanEdit

Function lua_lessthan:Int (lua_state:Byte Ptr, index1:Int, index2:Int)

Description: see Lua Reference Manual

Lua_loadEdit

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_newstateEdit

Function lua_newstate:Byte Ptr (f:Byte Ptr(ud:Byte Ptr, p:Byte Ptr, osize:Int, nsize:Int)

Description: see Lua Reference Manual

Lua_newthreadEdit

Function lua_newthread:Byte Ptr (lua_state:Byte Ptr)

Description: see Lua Reference Manual

Lua_newuserdataEdit

Function lua_newuserdata:Byte Ptr (lua_state:Byte Ptr, size:Int)

Description: see Lua Reference Manual

Lua_nextEdit

Function lua_next:Int (lua_state:Byte Ptr, index:Int)

Description: see Lua Reference Manual

Lua_objlenEdit

Function lua_objlen:Int (lua_state:Byte Ptr, index:Int)

Description: see Lua Reference Manual

Lua_pcallEdit

Function lua_pcall:Int (lua_state:Byte Ptr, nargs:Int, nresults:Int, errfunc:Int)

Description: see Lua Reference Manual

Lua_pushbooleanEdit

Function lua_pushboolean (lua_state:Byte Ptr, b:Int)

Description: see Lua Reference Manual

Lua_pushcclosureEdit

Function lua_pushcclosure (lua_state:Byte Ptr, fn:Int(ls:Byte Ptr)

Description: see Lua Reference Manual

Lua_pushintegerEdit

Function lua_pushinteger (lua_state:Byte Ptr, n:Int)

Description: see Lua Reference Manual

Lua_pushlightuserdataEdit

Function lua_pushlightuserdata (lua_state:Byte Ptr, p:Byte Ptr)

Description: see Lua Reference Manual

Lua_pushlstringEdit

Function lua_pushlstring (lua_state:Byte Ptr, s:Byte Ptr, size:Int)

Description: see Lua Reference Manual

Lua_pushnilEdit

Function lua_pushnil (lua_state:Byte Ptr)

Description: see Lua Reference Manual

Lua_pushnumberEdit

Function lua_pushnumber (lua_state:Byte Ptr, n:Double)

Description: see Lua Reference Manual

Lua_pushstringEdit

Function lua_pushstring (lua_state:Byte Ptr, s$z)

Description: see Lua Reference Manual

Lua_pushthreadEdit

Function lua_pushthread:Int (lua_state:Byte Ptr)

Description: see Lua Reference Manual

Lua_pushvalueEdit

Function lua_pushvalue (lua_state:Byte Ptr, index:Int)

Description: see Lua Reference Manual

Lua_rawequalEdit

Function lua_rawequal:Int (lua_state:Byte Ptr, index1:Int, index2:Int)

Description: see Lua Reference Manual

Lua_rawgetEdit

Function lua_rawget (lua_state:Byte Ptr, index:Int)

Description: see Lua Reference Manual

Lua_rawgetiEdit

Function lua_rawgeti (lua_state:Byte Ptr, index:Int, n:Int)

Description: see Lua Reference Manual

Lua_rawsetEdit

Function lua_rawset (lua_state:Byte Ptr, index:Int)

Description: see Lua Reference Manual

Lua_rawsetiEdit

Function lua_rawseti (lua_state:Byte Ptr, index:Int, n:Int)

Description: see Lua Reference Manual

Lua_removeEdit

Function lua_remove (lua_state:Byte Ptr, index:Int)

Description: see Lua Reference Manual

Lua_replaceEdit

Function lua_replace (lua_state:Byte Ptr, index:Int)

Description: see Lua Reference Manual

Lua_resumeEdit

Function lua_resume:Int (lua_state:Byte Ptr, narg:Int)

Description: see Lua Reference Manual

Lua_setallocfEdit

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_setfenvEdit

Function lua_setfenv:Int (lua_state:Byte Ptr, index:Int)

Description: see Lua Reference Manual

Lua_setfieldEdit

Function lua_setfield (lua_state:Byte Ptr, index:Int, k$z)

Description: see Lua Reference Manual

Lua_sethookEdit

Function lua_sethook:Int (lua_state:Byte Ptr, f(ls:Byte Ptr,ar:lua_Debug Ptr)

Description: see Lua Reference Manual

Lua_setlocalEdit

Function lua_setlocal$z (lua_state:Byte Ptr, ar:lua_Debug Ptr, n:Int)

Description: see Lua Reference Manual

Lua_setmetatableEdit

Function lua_setmetatable:Int (lua_state:Byte Ptr, index:Int)

Description: see Lua Reference Manual

Lua_settableEdit

Function lua_settable (lua_state:Byte Ptr, index:Int)

Description: see Lua Reference Manual

Lua_settopEdit

Function lua_settop (lua_state:Byte Ptr, index:Int)

Description: see Lua Reference Manual

Lua_setupvalueEdit

Function lua_setupvalue$z (lua_state:Byte Ptr, funcindex:Int, n:Int)

Description: see Lua Reference Manual

Lua_statusEdit

Function lua_status:Int (lua_state:Byte Ptr)

Description: see Lua Reference Manual

Lua_tobooleanEdit

Function lua_toboolean:Int (lua_state:Byte Ptr, index:Int)

Description: see Lua Reference Manual

Lua_tocfunctionEdit

Function lua_tocfunction:Byte Ptr (lua_state:Byte Ptr, index:Int)

Description: see Lua Reference Manual

Lua_tointegerEdit

Function lua_tointeger:Int (lua_state:Byte Ptr, index:Int)

Description: see Lua Reference Manual

Lua_tolstringEdit

Function lua_tolstring:Byte Ptr (lua_state:Byte Ptr, index:Int, size:Int Ptr)

Description: see Lua Reference Manual

Lua_tonumberEdit

Function lua_tonumber:Double (lua_state:Byte Ptr, index:Int)

Description: see Lua Reference Manual

Lua_topointerEdit

Function lua_topointer:Byte Ptr (lua_state:Byte Ptr, index:Int)

Description: see Lua Reference Manual

Lua_tothreadEdit

Function lua_tothread:Byte Ptr (lua_state:Byte Ptr, index:Int)

Description: see Lua Reference Manual

Lua_touserdataEdit

Function lua_touserdata:Byte Ptr (lua_state:Byte Ptr, index:Int)

Description: see Lua Reference Manual

Lua_typeEdit

Function lua_type:Int (lua_state:Byte Ptr, index:Int)

Description: see Lua Reference Manual

Lua_typenameEdit

Function lua_typename$z (lua_state:Byte Ptr, tp:Int)

Description: see Lua Reference Manual

Lua_xmoveEdit

Function lua_xmove (fromState:Byte Ptr, toState:Byte Ptr, n:Int)

Description: see Lua Reference Manual

Lua_yieldEdit

Function lua_yield:Int (lua_state:Byte Ptr, nresults:Int)

Description: see Lua Reference Manual

Lua_getglobalEdit

Function lua_getglobal (lua_state:Byte Ptr, name:String)

Description: see Lua Reference Manual

Lua_isbooleanEdit

Function lua_isboolean:Int (lua_state:Byte Ptr, index:Int)

Description: see Lua Reference Manual

Lua_isfunctionEdit

Function lua_isfunction:Int (lua_state:Byte Ptr, index:Int)

Description: see Lua Reference Manual

Lua_islightuserdataEdit

Function lua_islightuserdata:Int (lua_state:Byte Ptr, index:Int)

Description: see Lua Reference Manual

Lua_isnilEdit

Function lua_isnil:Int (lua_state:Byte Ptr, index:Int)

Description: see Lua Reference Manual

Lua_isnoneEdit

Function lua_isnone:Int (lua_state:Byte Ptr, index:Int)

Description: see Lua Reference Manual

Lua_isnoneornilEdit

Function lua_isnoneornil:Int (lua_state:Byte Ptr, index:Int)

Description: see Lua Reference Manual

Lua_istableEdit

Function lua_istable:Int (lua_state:Byte Ptr, index:Int)

Description: see Lua Reference Manual

Lua_isthreadEdit

Function lua_isthread:Int (lua_state:Byte Ptr, index:Int)

Description: see Lua Reference Manual

Lua_newtableEdit

Function lua_newtable (lua_state:Byte Ptr)

Description: see Lua Reference Manual

Lua_popEdit

Function lua_pop (lua_state:Byte Ptr, n:Int)

Description: see Lua Reference Manual

Lua_pushcfunctionEdit

Function lua_pushcfunction (lua_state:Byte Ptr, fn:Int(ls:Byte Ptr)

Description: see Lua Reference Manual

Lua_registerEdit

Function lua_register (lua_state:Byte Ptr, name:String, f:Int(ls:Byte Ptr)

Description: see Lua Reference Manual

Lua_setglobalEdit

Function lua_setglobal (lua_state:Byte Ptr, name:String)

Description: see Lua Reference Manual

Lua_tostringEdit

Function lua_tostring:String (lua_state:Byte Ptr, index:Int)

Description: see Lua Reference Manual

LuaL_addlstringEdit

Function luaL_addlstring (B:Byte Ptr, s:Byte Ptr, l:Int)

Description: see Lua Reference Manual

LuaL_addsizeEdit

Function luaL_addsize (B:Byte Ptr, size:Int)

Description: see Lua Reference Manual

LuaL_addstringEdit

Function luaL_addstring (B:Byte Ptr, s$z)

Description: see Lua Reference Manual

LuaL_addvalueEdit

Function luaL_addvalue (B:Byte Ptr)

Description: see Lua Reference Manual

LuaL_argerrorEdit

Function luaL_argerror:Int (lua_state:Byte Ptr, narg:Int, extramsg$z)

Description: see Lua Reference Manual

LuaL_buffinitEdit

Function luaL_buffinit (lua_state:Byte Ptr, B:Byte Ptr)

Description: see Lua Reference Manual

LuaL_callmetaEdit

Function luaL_callmeta:Int (lua_state:Byte Ptr, obj:Int, e$z)

Description: see Lua Reference Manual

LuaL_checkanyEdit

Function luaL_checkany (lua_state:Byte Ptr, narg:Int)

Description: see Lua Reference Manual

LuaL_checkintegerEdit

Function luaL_checkinteger:Int (lua_state:Byte Ptr, narg:Int)

Description: see Lua Reference Manual

LuaL_checklstringEdit

Function luaL_checklstring:Byte Ptr (lua_state:Byte Ptr, narg:Int, size:Int Ptr)

Description: see Lua Reference Manual

LuaL_checknumberEdit

Function luaL_checknumber:Double (lua_state:Byte Ptr, narg:Int)

Description: see Lua Reference Manual

LuaL_checkstackEdit

Function luaL_checkstack (lua_state:Byte Ptr, sz:Int, msg$z)

Description: see Lua Reference Manual

LuaL_checktypeEdit

Function luaL_checktype (lua_state:Byte Ptr, narg:Int, t:Int)

Description: see Lua Reference Manual

LuaL_checkudataEdit

Function luaL_checkudata:Byte Ptr (lua_state:Byte Ptr, narg:Int, tname$z)

Description: see Lua Reference Manual

LuaL_getmetafieldEdit

Function luaL_getmetafield:Int (lua_state:Byte Ptr, obj:Int, e$z)

Description: see Lua Reference Manual

LuaL_gsubEdit

Function luaL_gsub$z (lua_state:Byte Ptr, s$z, p$z, r$z)

Description: see Lua Reference Manual

LuaL_loadbufferEdit

Function luaL_loadbuffer:Int (lua_state:Byte Ptr, buff:Byte Ptr, sz:Int, name$z)

Description: see Lua Reference Manual

LuaL_loadfileEdit

Function luaL_loadfile:Int (lua_state:Byte Ptr, filename$z)

Description: see Lua Reference Manual

LuaL_loadstringEdit

Function luaL_loadstring:Int (lua_state:Byte Ptr, s$z)

Description: see Lua Reference Manual

LuaL_newmetatableEdit

Function luaL_newmetatable:Int (lua_state:Byte Ptr, tname$z)

Description: see Lua Reference Manual

LuaL_newstateEdit

Function luaL_newstate:Byte Ptr ()

Description: see Lua Reference Manual

LuaL_openlibsEdit

Function luaL_openlibs (lua_state:Byte Ptr)

Description: see Lua Reference Manual

LuaL_optintegerEdit

Function luaL_optinteger:Int (lua_state:Byte Ptr, narg:Int, d:Int)

Description: see Lua Reference Manual

LuaL_optlstringEdit

Function luaL_optlstring:Byte Ptr (lua_state:Byte Ptr, narg:Int, d$z, size:Int Ptr)

Description: see Lua Reference Manual

LuaL_optnumberEdit

Function luaL_optnumber:Double (lua_state:Byte Ptr, narg:Int, d:Double)

Description: see Lua Reference Manual

LuaL_prepbufferEdit

Function luaL_prepbuffer:Byte Ptr (B:Byte Ptr)

Description: see Lua Reference Manual

LuaL_pushresultEdit

Function luaL_pushresult (B:Byte Ptr)

Description: see Lua Reference Manual

LuaL_refEdit

Function luaL_ref:Int (lua_state:Byte Ptr, t:Int)

Description: see Lua Reference Manual

LuaL_registerEdit

Function luaL_register (lua_state:Byte Ptr, libname$z, l:lua_Reg Ptr)

Description: see Lua Reference Manual

LuaL_typerrorEdit

Function luaL_typerror:Int (lua_state:Byte Ptr, narg:Int, tname$z)

Description: see Lua Reference Manual

LuaL_unrefEdit

Function luaL_unref (lua_state:Byte Ptr, t:Int, ref:Int)

Description: see Lua Reference Manual

LuaL_whereEdit

Function luaL_where (lua_state:Byte Ptr, lvl:Int)

Description: see Lua Reference Manual

LuaL_addcharEdit

Function luaL_addchar (B:Byte Ptr, c:String)

Description: see Lua Reference Manual

LuaL_argcheckEdit

Function luaL_argcheck (lua_state:Byte Ptr, cond:Int, narg:Int, extramsg:String)

Description: see Lua Reference Manual

LuaL_checkintEdit

Function luaL_checkint:Int (lua_state:Byte Ptr, narg:Int)

Description: see Lua Reference Manual

LuaL_checklongEdit

Function luaL_checklong:Long (lua_state:Byte Ptr, narg:Int)

Description: see Lua Reference Manual

LuaL_checkstringEdit

Function luaL_checkstring:String (lua_state:Byte Ptr, narg:Int)

Description: see Lua Reference Manual

LuaL_dofileEdit

Function luaL_dofile:Int (lua_state:Byte Ptr, filename:String)

Description: see Lua Reference Manual

LuaL_dostringEdit

Function luaL_dostring:Int (lua_state:Byte Ptr, str:String)

Description: see Lua Reference Manual

LuaL_getmetatableEdit

Function luaL_getmetatable (lua_state:Byte Ptr, tname:String)

Description: see Lua Reference Manual

LuaL_optintEdit

Function luaL_optint:Int (lua_state:Byte Ptr, narg:Int, d:Int)

Description: see Lua Reference Manual

LuaL_optlongEdit

Function luaL_optlong:Long (lua_state:Byte Ptr, narg:Int, d:Long)

Description: see Lua Reference Manual

LuaL_optstringEdit

Function luaL_optstring:String (lua_state:Byte Ptr, narg:Int, d:String)

Description: see Lua Reference Manual

LuaL_typenameEdit

Function luaL_typename:String (lua_state:Byte Ptr, idx:Int)

Description: see Lua Reference Manual