Lua Support

Overview

JamPlus has built in Lua support, provided through a minimal distribution of LuaPlus (http://luaplus.org/). Lua script may be run during the Parsing Phase and during the Updating Phase.

Any LuaBinaries capable module can run in the LuaPlus environment. Just drop the binary in the bin/LuaPlus/modules/ directory.

The scripts located in bin/scripts/ are written in Lua, although they are executed external to the Jam executable.

---

Using Lua during the Parsing Phase

There are two rules for execution of Lua script available for use during the rule parsing phase of JamPlus. They are rule LuaString LUA_SCRIPT and rule LuaFile LUA_FILENAME.

rule LuaString LUA_SCRIPT

Executes LUA_SCRIPT, returning any results back to the caller.

Parameters:

LUA_SCRIPT

Syntactically correct Lua script embedded in a string. Only the first string list item is executed.

Returns:

If the Lua script doesn't return any values, the return value is an empty list. If the Lua script does return values, the return values are transformed to a Jam string list. Nested tables are collapsed.

rule LuaFile LUA_FILENAME

Executes LUA_FILENAME, returning any results back to the caller.

Parameters:

LUA_FILENAME

The filename of the Lua script to run.

Returns:

If the Lua script doesn't return any values, the return value is an empty list. If the Lua script does return values, the return values are transformed to a Jam string list. Nested tables are collapsed.

---

Using Lua in Actions

Using the new lua modifier for an action, Lua script can be run in a thread within the Jam process.

actions lua RunLuaScript
{
    require 'iox'; iox.Sleep($(SLEEP)); print($(TEXT))
}

---

Accessing Jam from Lua

Within a Lua script, it is possible to access Jam variables and execute Jam rules.

function jam_getvar([ TARGET_NAME, ] VARIABLE_NAME)

Retrieves VARIABLE_NAME from the active Jam globals and returns it as a table of strings.

If TARGET_NAME is specified, VARIABLE_NAME is retrieved as if an on TARGET_NAME had been issued in Jam.

Parameters:

	TARGET_NAME	(optional) The target to make active to retrieve VARIABLE_NAME from.
	VARIABLE_NAME	The Jam variable to retrieve.

Returns:

All strings within the VARIABLE_NAME string are returned as a Lua array of strings.

function jam_setvar([ TARGET_NAME, ] VARIABLE_NAME, VALUE)

Sets VALUE into the active Jam global VARIABLE_NAME. VALUE can be a boolean, number, string, or table. Nested tables are collapsed.

If TARGET_NAME is specified, VALUE is set into VARIABLE_NAME as if an VARIABLE_NAME on TARGET_NAME had been issued in Jam.

Parameters:

	TARGET_NAME	(optional) The target to make active to set VARIABLE_NAME into.
	VARIABLE_NAME	The Jam variable to set.

function jam_evaluaterule(RULE_NAME [, PARAMETERS])

Executes rule RULE_NAME using any optional PARAMETERS specified. Returns the result as a Lua table.

Parameters:

	RULE_NAME	The name of any valid Jam rule.
	PARAMETERS	(optional) If specifed, the PARAMETERS are collapsed into a Jam string list and passed to the rule.

Returns:

If the Jam rule doesn't return any values, the return value is nil. If the Jam rule does return values, the return values are transformed to a Lua array of strings.

---

Examples

# Hello
LuaString "print('Hello')" ;

# 10 hi false
Echo [ LuaString "return { 10, 'hi', false }" ] ;

# 5.suf hello.suf true.suf
var = [ LuaString "return { 5, 'hello', true }" ] ;
Echo $(var:S=.suf) ;

#------------------------------------------------------------------------------
# Hello world!
var = Hello world! ;
Echo [ LuaString "return jam_getvar('var')" ] ;

# Hi everyone
LuaString "jam_setvar('var', 'Hi everyone')" ;
Echo $(var) ;

# Hi everyone
Echo [ LuaString "return jam_getvar('var')" ] ;

#------------------------------------------------------------------------------
# The Variable Contents
MyVariable on mytarget = The Variable Contents ;
Echo [ LuaString "return jam_getvar('mytarget', 'MyVariable')" ] ;

# **hello**
LuaString "jam_setvar('mytarget', 'MyVariable', '**hello**')" ;
Echo [ LuaString "return jam_getvar('mytarget', 'MyVariable')" ] ;

rule ReturnList INPUT
{
    return **$(INPUT)** ;
}

# **MyStuff** **YourStuff**
Echo [ LuaString "return jam_evaluaterule('ReturnList', { 'MyStuff', 'YourStuff' })" ] ;