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

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