Pub.Lua · BlitzMax

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

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.

Lua Documentation

Introduction

Setting up a Lua VM

Shutting down a Lua VM

Accessing Lua Globals

Registering BlitzMax Functions

Running Lua Scripts From Within BlitzMax

Functions

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

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

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

Function lua_close (lua_state:Byte Ptr)

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

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

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

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

Function lua_error:Int (lua_state:Byte Ptr)

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

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

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

Function lua_getfield (lua_state:Byte Ptr, index:Int, k$z) ' no 0 expected

Function lua_gethook:Byte Ptr (lua_state:Byte Ptr)

Function lua_gethookcount:Int (lua_state:Byte Ptr)

Function lua_gethookmask:Int (lua_state:Byte Ptr)

Function lua_getinfo:Int (lua_state:Byte Ptr, what$z, ar:lua_Debug Ptr) ' no 0 expected

Function lua_getlocal$z (lua_state:Byte Ptr, ar:lua_Debug Ptr, n:Int) ' no 0 expected

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

Function lua_getstack:Int (lua_state:Byte Ptr, level:Int, ar:lua_Debug Ptr) ' no 0 expected

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

Function lua_gettop:Int (lua_state:Byte Ptr)

Function lua_getupvalue$z (lua_state:Byte Ptr, funcindex:Int, n:Int) ' no 0 expected

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

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

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

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

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

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

Function lua_newthread:Byte Ptr (lua_state:Byte Ptr)

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

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

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

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

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

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

Function lua_pushnil (lua_state:Byte Ptr)

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

Function lua_pushstring (lua_state:Byte Ptr, s$z) ' no 0 expected

Function lua_pushthread:Int (lua_state:Byte Ptr)

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

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

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

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

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

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

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

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

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

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

Function lua_setfield (lua_state:Byte Ptr, index:Int, k$z) ' no 0 expected

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

Function lua_setlocal$z (lua_state:Byte Ptr, ar:lua_Debug Ptr, n:Int) ' no 0 expected

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

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

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

Function lua_setupvalue$z (lua_state:Byte Ptr, funcindex:Int, n:Int) ' no 0 expected

Function lua_status:Int (lua_state:Byte Ptr)

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

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

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

Function lua_tolstring:Byte Ptr (lua_state:Byte Ptr, index:Int, size:Size_T Ptr) ' without any conversion!

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

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

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

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

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

Function lua_typename$z (lua_state:Byte Ptr, tp:Int) ' no 0 expected

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

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

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

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

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

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

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

`Function lua_close (lua_state:Byte Ptr)`

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

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

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

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

`Function lua_error:Int (lua_state:Byte Ptr)`

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

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

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

`Function lua_getfield (lua_state:Byte Ptr, index:Int, k$z) ' no 0 expected`

`Function lua_gethook:Byte Ptr (lua_state:Byte Ptr)`

`Function lua_gethookcount:Int (lua_state:Byte Ptr)`

`Function lua_gethookmask:Int (lua_state:Byte Ptr)`

`Function lua_getinfo:Int (lua_state:Byte Ptr, what$z, ar:lua_Debug Ptr) ' no 0 expected`

`Function lua_getlocal$z (lua_state:Byte Ptr, ar:lua_Debug Ptr, n:Int) ' no 0 expected`

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

`Function lua_getstack:Int (lua_state:Byte Ptr, level:Int, ar:lua_Debug Ptr) ' no 0 expected`

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

`Function lua_gettop:Int (lua_state:Byte Ptr)`

`Function lua_getupvalue$z (lua_state:Byte Ptr, funcindex:Int, n:Int) ' no 0 expected`

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

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

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

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

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

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

`Function lua_newthread:Byte Ptr (lua_state:Byte Ptr)`

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

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

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

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

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

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

`Function lua_pushnil (lua_state:Byte Ptr)`

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

`Function lua_pushstring (lua_state:Byte Ptr, s$z) ' no 0 expected`

`Function lua_pushthread:Int (lua_state:Byte Ptr)`

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

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

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

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

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

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

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

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

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

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

`Function lua_setfield (lua_state:Byte Ptr, index:Int, k$z) ' no 0 expected`

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

`Function lua_setlocal$z (lua_state:Byte Ptr, ar:lua_Debug Ptr, n:Int) ' no 0 expected`

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

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

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

`Function lua_setupvalue$z (lua_state:Byte Ptr, funcindex:Int, n:Int) ' no 0 expected`

`Function lua_status:Int (lua_state:Byte Ptr)`

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

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

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

`Function lua_tolstring:Byte Ptr (lua_state:Byte Ptr, index:Int, size:Size_T Ptr) ' without any conversion!`

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

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

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

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

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

`Function lua_typename$z (lua_state:Byte Ptr, tp:Int) ' no 0 expected`

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

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

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

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

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

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

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

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

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

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

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

`Function lua_newtable (lua_state:Byte Ptr)`