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