|
@@ -5,52 +5,52 @@ 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.</span> " (from "<a href="../lua-5.1.4/doc/contents.html">Lua 5.1 Reference
|
|
|
Manual</a>" by Roberto Ierusalimschy, Luiz Henrique de
|
|
|
-Figueiredo, Waldemar Celes)<br><br>This module provides a
|
|
|
+Figueiredo, Waldemar Celes)<br/><br/>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).<br><br>The
|
|
|
+lists (which are not yet supported by BlitzMax).<br/><br/>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.<br><h2>Lua
|
|
|
+(or shared libraries, resp.) are no longer required.<br/><h2>Lua
|
|
|
Documentation</h2>The Lua Reference Manual is part of this
|
|
|
-distribution and may be directly visited from here:<br><ul><li><a href="../lua-5.1.4/doc/contents.html">Lua 5.1 Contents</a></li><li><a href="../lua-5.1.4/doc/manual.html">Lua 5.1 Reference Manual</a></li><li><a href="../lua-5.1.4/doc/readme.html">Lua 5.1 ReadMe</a></li></ul>Additional
|
|
|
+distribution and may be directly visited from here:<br/><ul><li><a href="../lua-5.1.4/doc/contents.html">Lua 5.1 Contents</a></li><li><a href="../lua-5.1.4/doc/manual.html">Lua 5.1 Reference Manual</a></li><li><a href="../lua-5.1.4/doc/readme.html">Lua 5.1 ReadMe</a></li></ul>Additional
|
|
|
information can be found on the <a href="http://www.lua.org">Lua
|
|
|
web site</a>; the <a href="http://lua-users.org/wiki/">Lua
|
|
|
wiki</a> contains further material <a href="http://lua-users.org/wiki/BlitzMax">about this module</a>
|
|
|
-and related packages.<br><h2>Introduction</h2>The
|
|
|
+and related packages.<br/><h2>Introduction</h2>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 <a href="../lua-5.1.4/doc/manual.html#3">Lua Reference manual</a><br><h3>Setting
|
|
|
+information can be found in the <a href="../lua-5.1.4/doc/manual.html#3">Lua Reference manual</a><br/><h3>Setting
|
|
|
up a Lua VM</h3>Running Lua scripts always require the
|
|
|
-instantiation of at least one Lua VM:<br><pre> local LuaState:byte ptr = luaL_newstate()</pre>The
|
|
|
+instantiation of at least one Lua VM:<br/><pre> local LuaState:byte ptr = luaL_newstate()</pre>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.<br><br>It
|
|
|
+passed as the first argument to almost any other Lua API function.<br/><br/>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):<br><pre> luaL_openlibs(LuaState)</pre>Always
|
|
|
+are not necessary):<br/><pre> luaL_openlibs(LuaState)</pre>Always
|
|
|
initialize the Lua VM by opening its libraries unless you really know
|
|
|
-what you are doing!<br><br>Usually, creating a single Lua
|
|
|
+what you are doing!<br/><br/>Usually, creating a single Lua
|
|
|
state is sufficient, even further (Lua) threads share the basic Lua
|
|
|
-state (and its associated environment).<br><h3>Shutting
|
|
|
+state (and its associated environment).<br/><h3>Shutting
|
|
|
down a Lua VM</h3>At the end, it's always a good idea to shut
|
|
|
-down the Lua VM<br><pre> lua_close(LuaState)</pre>The
|
|
|
+down the Lua VM<br/><pre> lua_close(LuaState)</pre>The
|
|
|
Lua interpreter has now been terminated and its state variable is no
|
|
|
-longer valid.<br><h3>Accessing Lua Globals</h3>The
|
|
|
-code<br><pre> lua_pushstring(LuaState, "BMXString")<br> lua_setglobal (LuaState, "luaglobal")</pre>defines
|
|
|
+longer valid.<br/><h3>Accessing Lua Globals</h3>The
|
|
|
+code<br/><pre> lua_pushstring(LuaState, "BMXString")<br/> lua_setglobal (LuaState, "luaglobal")</pre>defines
|
|
|
a global Lua variable (called <span style="font-family: Courier New,Courier,monospace;">luaglobal</span>)
|
|
|
which contains a string (namely "<span style="font-family: Courier New,Courier,monospace;">BMXString</span>").<h3>Registering
|
|
|
BlitzMax Functions</h3>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.<br><br>Such
|
|
|
-BlitzMax functions typically look as follows:<br><pre> function BMXName:int (LuaState:Byte Ptr)<br> ... ' handling of parameters passed from Lua (if required)<br> ... ' actual function body<br> ... ' passing results back to Lua (if required)<br> return 0 ' number of values returned to Lua<br> end function</pre>Such
|
|
|
-a function is then registered using<br><pre> lua_register(LuaState, "luaname", BMXName)</pre>This
|
|
|
+functions and register them in the Lua VM.<br/><br/>Such
|
|
|
+BlitzMax functions typically look as follows:<br/><pre> function BMXName:int (LuaState:Byte Ptr)<br/> ... ' handling of parameters passed from Lua (if required)<br/> ... ' actual function body<br/> ... ' passing results back to Lua (if required)<br/> return 0 ' number of values returned to Lua<br/> end function</pre>Such
|
|
|
+a function is then registered using<br/><pre> lua_register(LuaState, "luaname", BMXName)</pre>This
|
|
|
command registers a BlitzMax function (called <span style="font-family: Courier New,Courier,monospace;">BMXName</span>)
|
|
|
with the (global) name <span style="font-family: Courier New,Courier,monospace;">luaname</span>
|
|
|
-under Lua. Both names may be equal, but they do not have to.<br><h3>Running
|
|
|
-Lua Scripts From Within BlitzMax</h3>The code<br><pre> local Result:int = luaL_loadString(LuaState,LuaScript)<br> if (Result <> 0) then<br> ' ERROR!!!<br> lua_close(LuaState) ' just to be complete<br> end<br> end if</pre>loads
|
|
|
+under Lua. Both names may be equal, but they do not have to.<br/><h3>Running
|
|
|
+Lua Scripts From Within BlitzMax</h3>The code<br/><pre> local Result:int = luaL_loadString(LuaState,LuaScript)<br/> if (Result <> 0) then<br/> ' ERROR!!!<br/> lua_close(LuaState) ' just to be complete<br/> end<br/> end if</pre>loads
|
|
|
and compiles a (BlitzMax) string containing a LuaScript. The result (of
|
|
|
-compilation) is left on the (Lua) stack.<br><pre> lua_getfield(LuaState, LUA_GLOBALSINDEX, "debug")' get global "debug"<br> lua_getfield(LuaState, -1, "traceback") ' get "debug.traceback"<br> lua_remove (LuaState, -2) ' remove "debug" table from stack<br><br> Result = lua_pcall(LuaState,1,-1,-1)' use "debug.traceback" as err.hdlr<br> if (Result <> 0) then<br> ' ERROR<br> lua_close(LuaState) ' just to be complete<br> end<br> end if</pre>actually
|
|
|
+compilation) is left on the (Lua) stack.<br/><pre> lua_getfield(LuaState, LUA_GLOBALSINDEX, "debug")' get global "debug"<br/> lua_getfield(LuaState, -1, "traceback") ' get "debug.traceback"<br/> lua_remove (LuaState, -2) ' remove "debug" table from stack<br/><br/> Result = lua_pcall(LuaState,1,-1,-1)' use "debug.traceback" as err.hdlr<br/> if (Result <> 0) then<br/> ' ERROR<br/> lua_close(LuaState) ' just to be complete<br/> end<br/> end if</pre>actually
|
|
|
evaluates the previously loaded script. The initially mentioned Lua
|
|
|
commands just prepare for proper error messages should the Lua script
|
|
|
fail.</div>
|