The core language (eg. syntax, behavior, semantics) is Lua 5.1. This is covered in great detail in section 2 of the Lua 5.1 manual. Some changes are made to the core language though:

• then is optional in if statements
• do is optional in for or while loops
• != behaves just like ~= (either can be used)
• Generic for loops can iterate over tables, as in Lua 5.0
• The pipe character (|) is shorthand for return
• Anonymous functions can be defined in a shorthand manner (details)
• The metatable event "__updateindex" is the compliment of "__newindex" and is called when setting a value to a key in a table when the key already exists in the table.

The basic functions from the standard library are the same as in Lua 5.1, with the following changes:

next (table [[, ...], index])

The table argument can be an RGD file object or an RGD table object, at which point the 'children' member of the object is used as the table

pairs (table)

The table argument can be an RGD file object or an RGD table object

print ([e1 [, e2 [, ...]]])

Each argument is converted to a string and then written to output window, then a line break is written after the last argument

type (v)

Returns "userdata" for RGD file objects and RGD table objects

The coroutine manipulation sub-library of the standard library is the same as in Lua 5.1, with no changes.

The string manipulation sub-library of the standard library is the same as in Lua 5.1, with the following additions:

string.split(s [, delimiter [, plain]])

Splits up s into segments using the string.find function (eg. delimiter is a pattern unless plain is given and a true value). Returns a table with the first substring at t[1] and the last substring at t[n]. Delimiter defaults to " " if not given, thereby splitting the string into words. If plain is true, then string.split is the reverse of table.concat.

string.after(s, needle)

Returns the substring of s after the first occurance of needle (does not use pattern matching). Returns an empty string if needle is not found.

string.afterlast(s, needle)

Returns the substring of s after the last occurance of needle (does not use pattern matching). Returns s if needle is not found.

string.before(s, needle)

Returns the substring of s before the first occurance of needle (does not use pattern matching). Returns s if needle is not found.

string.beforelast(s, needle)

Returns the substring of s before the last occurance of needle (does not use pattern matching). Returns an empty string if needle is not found.

string.formatself(s, format [, ...])

Equivalent to string.format(format, s, ...), useful when using a string in an object oriented manner.

The table manipulation sub-library of the standard library is the same as in Lua 5.1, but be aware of the following:
RGD file objects and RGD table objects are classed as "userdata" rather than "table". Therefore nothing in the table library will work on RGD file objects or RGD table objects. Even if they did, most of the table library works on tables as arrays, and RGD table objects can only have string keys, not number keys. RGD file objects can only contain "GameData" as a key, so the table library would be of little use here too.
There are also the following additions:

table([t])

Equivalent to setmetatable(t or {},{__index=table}). Returns either t or a new empty table, with a metatable that points to the table table, so that the resulting table can be used in an object oriented manner.

table.filter(t, f)

For each key/value pair in t (which can be a table, or an RGD table object), f(key, value) is called. If a value of false is returned, then that key/value pair is erased from t. filter returns t.

The mathematical functions from the standard library are the same as in Lua 5.1, with the following additions: (all integer variables can be used in an object oriented way: n:clamp(x,y) is the same as math.clamp(n,x,y))

math.clamp(n [, lower [, upper]])

Clamps n into the range lower to upper. Equivalent to:
if upper and n > upper then return upper end
if lower and n < lower then return lower end
return n


math.formatself(n, format [, ...])

Equivalent to string.format(format, n, ...), useful when using a number in an object oriented manner.

The input and output facilities of the standard library are the same as in Lua 5.1, with the following changes:

io.stdin
io.stdout
io.stderr

These are not available.

io.close ([file])
io.flush ()
io.input ([file])
io.lines ([filename])
io.open (filename [, mode])
io.output ([file])
io.popen (prog [, mode])
io.read (format1, ...)
io.tmpfile ()
io.type (obj)
io.write (value1, ...)

Each of these functions is security protected. Whenever one is called, if the user has not given permission for the IO library to be used, then the user is asked to give or withhold permission. If permission is not given, then the function returns nil. Once the user has given permission for the IO library to be used, then all of the functions can be used without permission being needed again.

The operating system facilities of the standard library are the same as in Lua 5.1, with the following changes:

os.clock ()
os.date ([format [, time]])
os.difftime (t2, t1)
os.execute (command)
os.exit ([code])
os.getenv (varname)
os.remove (filename)
os.rename (oldname, newname)
os.setlocale (locale [, category])
os.time ([table])
os.tmpname ()

Each of these functions is security protected. Whenever one is called, if the user has not given permission for the OS library to be used, then the user is asked to give or withhold permission. If permission is not given, then the function returns nil. Once the user has given permission for the OS library to be used, then all of the functions can be used without permission being needed again.

The reflexive debug interface of the standard library are the same as in Lua 5.1, with the following changes:

debug.debug ()

This function is not available.

debug.getfenv (o)
debug.gethook ([thread])
debug.getinfo ([thread,] function [, what])
debug.getlocal ([thread,] level, local)
debug.getmetatable (object)
debug.getregistry ()
debug.getupvalue (func, up)
debug.setfenv (object, table)
debug.sethook ([thread,] hook, mask [, count])
debug.setlocal (level, local, value)
debug.setmetatable (object, table)
debug.setupvalue (func, up, value)

Each of these functions is security protected. Whenever one is called, if the user has not given permission for the debug library to be used, then the user is asked to give or withhold permission. If permission is not given, then the function returns nil. Once the user has given permission for the debug library to be used, then all of the functions can be used without permission being needed again.

each_file(rgd)

If this function is provided by the macro, then it is called for each RGD in the folder (and sub-folders) that the macro is being run over. rgd is an RGD file object

at_end()

If this function is provided by the macro, then it is called after each_file has been called for each RGD

UCS(v)

If v is a string of the form "$1234" (eg. matching the lua pattern "^$[0-9]*$") or v is a number, then the return value is the equivalent value from the loaded UCS files, or "$1234 no key" if not found. Note that as lua uses ASCII strings, characters outside the ASCII character set will not be neatly converted to ASCII. If v is not a number and not a string of UCS form, then v is the return value.

loadRgd(filepath)

Loads the specified file and returns an RGD file object. filepath should be a full path (eg. "attrib\attrib\ebps\file.rgd" or "data\attrib\ebps\file.rgd") using backslashes and not using forward slashes nor "." nor "..". For example:
rgd = loadRgd("attrib\\attrib\\ebps\\filename.rgd")
rgd = loadRgd([[data\attrib\racebps\filename.rgd]])
If filepath is outside of the folder that the macro is being run over, and the user has not given permission for files outside the folder to be loaded, then the user will be asked to give or withhold permission. If permission is not given, then nil is returned. If the specified file cannot be loaded, then an error is generated, causing control flow to jump to where the application called the macro, or the most recent pcall.

rgd.name

The filename of the rgd (eg. "allies.rgd"). This value is read-only

rgd.path

The filepath of the rgd (eg. "attrib\attrib\racebps\allies.rgd"). This value is read-only

rgd:save()

Equivalent to rgd:saveAs(rgd.path)

rgd:saveAs(filepath)

Saves the RGD to the specified location. filepath should be a full path (eg. "attrib\attrib\ebps\file.rgd" or "data\attrib\ebps\file.rgd") using backslashes and not using forward slashes nor "." nor "..". If filepath is outside of the folder that the macro is being run over, and the user has not given permission for files to be saved to outside the folder, then the user will be asked to give or withhold permission. If permission is not given, then nil is returned. If the specified file cannot be saved to, then an error is generated, causing control flow to jump to where the application called the macro, or the most recent pcall.

rgd.GameData

The GameData table of the rgd file. Note that the RGD is not actually loaded from disk until the value of rgd.GameData is actually needed. This value is an RGD table object rather than a lua table

rgd.children

Equivalent to {GameData = rgd.GameData}

rgd:GET(a1 [, a2 [, ...]])

Returns the value of rgd[a1][a2]...[an] or nil if it doesn't exist. Note that a1 must be "GameData". Nearly equivalent to:
rgd[a1] and rgd[a1][a2] ... and rgd[a1][a2]...[an]

rgd:SET(a1 [, a2 [, ...]], v)

Sets rgd[a1][a2]...[an] to v. Note that a1 must be "GameData". Nearly equivalent to:
rgd:GET(a1,a2,...) and rgd[a1][a2]...[an] = v

rgd([key])

Equivalent to next(rgd.children, key), thus allowing an RGD file object to be used in a generic for statement, like so:
for k,v in rgd do print(k .. " = " .. v) end

t["$REF"]

The reference of the table (a string if present; nil otherwise)

t.children

A lua table containing the children of the table object in form {k1 = t[k1], k2 = t[k2] ... kn = t[kn]}. Note that if the table object has a reference, then "$REF" is included in this lua table.

t["key"]
t.key

The value of the specified key in the table. Values are mapped like so:
string values => "value"
numeric values => 3.14159
boolean values => true / false
DoW UCS reference => "$12345"
CoH UCS reference => "$12345"
sub-table values => RGD table object
Keys may only be strings; use t["1"] rather than t[1].

t["key"] = v
t.key = v

Copies v into t.key. This means that when v is a lua table or RGD table object, then the contents of v are copied into t.key rather than a reference to v

t:GET(a1 [, a2 [, ...]])

Returns t[a1][a2]...[an] if present, or nil if it doesn't exist. Nearly equivalent to:
t[a1] and t[a1][a2] ... and t[a1][a2]...[an]

t:SET([a1 [, a2 [, ...]] ,] v)

Sets t[a1][a2]...[an] to v. If v is the only argument, then it must be a lua table or an RGD table object, at which point the contents of v are copied into t.

t([key])

Equivalent to next(t.children, key), thus allowing an RGD table object to be used in a generic for statement, like so:
for k,v in t do print(k .. " = " .. v) end

Back to advanced topics list

This documentation is provided under the GNU General Public License. All trademarks / copyrights are tm/r/c their respective owners.