Available Standard Lua Functions

Besides of special ArmyCalc API (functions beginning with 'tw...'), there are a lot of standard Lua functions available in both validation and display scripts.

In some implementations your code will be run in a special environment (so called 'sandbox').
Not all standard Lua functions are safe to run in such environment. Thats why not all of them are available.

Following is an official list of functions with short usage descriptions that should be supported in any program implementing the TWR file format.
If you will use functions from this list your Ruleset should work without any problems in such program.

For details on any function see Lua manual at lua.org.

List Sections:

• Basic Functions
• Coroutine Manipulation
• String Manipulation
• Table Manipulation
• Mathematical Functions
• Appendix. Lua Resources

Basic Functions

1. assert( v [, message] )
   Generates an error if value of v is nil or false.
2. error( message [, level] )
   Terminates function call and generates an error.
3. ipairs( table )
   Can be used to iterate over table elements like: for index,value in ipairs(table) do something() end. It will iterate only trough element with indexes like: 1, 2, 3, ..
4. next( table [, index] )
   Returns index and value of the first table element or element just after index when index is not given.
5. pairs( table )
   Can be used to iterate over table elements like: for index,value in ipairs(table) do something() end. It will iterate trough all elements, including indexed with strings etc.
6. pcall( f [, arg1 , arg2 ..] )
   Calls function f in protected mode. Can be used to catch errors.
7. select( index, ... )
   Returns arguments after index.
8. tonumber( e [, base] )
   Tries to convert e to number or returns nil.
9. tostring( e )
   Converts e (of any type) to string.
10. type( v )
    Returns the string describing type of v. One of: "nil", "number", "string", "boolean", "table", "function", "thread", and "userdata".
11. unpack( list [, i [, j [...]]] )
    Returns elements from the list.
12. xpcall( f , err )
    Similar to pcall but you can set your own error handler.

Coroutine Manipulation

Coroutines allows script to do multiple tasks at once. Use of multi-threaded programing in Rulesets scripting would be pretty hard to find. However, this functions are marked as safe to run in sandbox so they are listed here for clearness sake. Visit Lua Coroutines Tutorial at Lua users wiki for details.

1. coroutine.create()
   
2. coroutine.resume()
   
3. coroutine.running()
   
4. coroutine.status()
   
5. coroutine.wrap()
   

String Manipulation

This functions should be also available in an object programming style. For example "string.rep( s , n )" equals "s:rep( n )". Lua string chars and tables are indexed from 1.

1. string.byte( s [, i [, j]])
   Returns codes of characters from i to j.
2. string.char( c1 [, c2 [...]] )
   Returns string build from characters of codes c1 , c2 , ...
3. string.find( s , pattern [, init [, plain]])
   Returns nil or position of pattern in s. Starts searching from init index. If plain is given function do not use regexps.
4. string.format( formatstring , ... )
   Works similar to C printf() function. Returns formatstring with special characters like "%d" "%c" etc. replaced with function further arguments.
5. string.gmatch( s , pattern )
   Can be used to iterate trough all instances of pattern in s.
6. string.gsub( s , pattern , repl [, n])
   Returns copy of s with all(or first n) occurrences of pattern replaced with repl.
7. string.len( s )
   Returns number of chars in string.
8. string.lower( s )
   Returns s with uppercase characters converted to lowercase.
9. string.match( s , pattern [, init])
   Finds pattern in s. Search from beginning or from init index.
10. string.rep( s , n )
    Returns string which is n times repetition of s.
11. string.reverse( s )
    Returns backward s.
12. string.sub( s , i [, j])
    Returns substring of s from index i to end or index j.
13. string.upper( s )
    Returns s with lowercase characters converted to uppercase.

Table Manipulation

1. table.insert( table , [pos ,] value )
   Inserts value as the next natural indexed element of table. If pos is given all table elements from pos are shifted one index up and tab[pos] is set to value.
2. table.maxn( table )
   Returns 0 or max numeric index of table.
3. table.remove( table [, pos])
   It sets table[pos]=nil and shifts all elements after pos one index down.
4. table.sort( table [, comp])
   Sorts all elements in table from 1 to table size. Uses standard Lua < operator to compare values or comp( arg1 , arg2 ) function if given.

Mathematical Functions

math table gives you access to common mathematical operations. See Lua Math Library Tutorial at Lua users wiki for details.

1. math.abs( x )
   Returns absolute value of x
2. math.acos( x )
   Arccosine of x
3. math.asin( x )
   Arcsine of x
4. math.atan( x )
   Arctangent of x
5. math.atan2( y , x )
   Arctangent of x/y
6. math.ceil( x )
   Returns smallest integer no smaller than x
7. math.cos( x )
   Cosine of x
8. math.cosh( x )
   Hyperbolic cosine
9. math.deg( x )
   Convert x from radians to degrees
10. math.exp( x )
    Returns 'e' to the power of x
11. math.floor( x )
    Returns biggest integer no greater then x
12. math.fmod( x , y )
    Returns x modulo y
13. math.frexp( x )
    Splits x into a normalised fraction and an exponent
14. math.huge
    Represents infinity. ( math.huge == (1/0) )
15. math.ldexp( m , e )
    Inverse function of math.frexp().
16. math.log( x )
    Natural logarithm of x
17. math.log10( x )
    Base 10 logarithm of x
18. math.max( x , ... )
    Returns the largest parameter
19. math.min( x , ... )
    Returns the smallest parameter
20. math.modf( x )
    Returns integral and fractional parts of x
21. math.pi
    Returns Pi
22. math.pow( x , y )
    Returns x to the power of y
23. math.rad( s )
    Converts x from degrees to radians
24. math.random( [ [lower ,] upper] )
    Without parameters generates real number between 0 and 1. With upper given generates random integer between 1 and upper. Otherwise generates random integer between lower and upper.
25. math.sin( x )
    Sine of x
26. math.sinh( x )
    Hyperbolic sine of x
27. math.sqrt( x )
    Square root of x
28. math.tan( x )
    Tangent of x
29. math.tanh( x )
    Hyperbolic tangent of x

Appendix. Lua Resources

• lua.org - biggest source of materials about Lua. Manuals, tutorials, users-wiki ..
• Google + "Lua tutorial"
• Example Rulesets - You can also watch example Rulesets in Your Rulesets section to see well commented examples of scripts.