[Last Change: 13 Feb 2012 (rev 6)]

Lua

Lua is a concise, easy to learn scripting language. Here's a very brief primer with all that you'll need to know to create simple source definitions. For more information you can visit Learning Lua, or read the full documentation.

Statements

Lua statements (e.g. assignments, control sequences, etc) may stretch across multiple lines and may be followed by an optional semi-colon (;). To place multiple statements on a single line, terminate each statement with a semi-colon:

a = 1; b = 2; c = 3;

Comments start with two hyphens -- and extend to the end of the line.

-- this is a comment
a = 1 -- this is also a comment

Variables

Variables can contain numbers, strings, and tables (which are collections of pairs of keys and values). Lua is not a strongly typed language, which means that a variable can contain any type of value. To assign a value:

-- numbers are always floating point
spectrum = 1.49

-- strings can be enclosed in single or double quotes
vstring = "this is a string"

-- tables can have keys and values of any type and can contain heterogeneous data
vtable = { a = 3, b = 2, c = "values in a table can have any type" }

You can copy variable values:

a = 1
b = a -- copy value from a to b
a = 2 -- b is still equal to 1

However, if you copy a variable containing a table, you don't create a new table, you create reference to the original:

a = { key1 = 2, key2 = 3 }
b = a      -- creates new reference to table
b.key1 = 4 -- both b.key1 and a.key1 are now equal to 4

Tables

To generate sources and control the raytrace you will call SAOTrace provided functions, which usually require that you pass them a table of key - value pairs. This makes it easy to remember what value goes with which parameter. For example,

point{ position = { theta = 10, phi = 22 },
       spectrum = 1.49
     }

Tables are created using curly braces:

{ a = 2, b = 3 }

This creates a table with two entries with string keys a and b. If you don't specify a key then Lua will generate an integer key for it:

{ "first", "second" }

is equivalent to

{ 1 = "first", 2 = "second" }

This is how Lua implements lists. For more information, see §2.5.7 of the Lua manual.

To access an element in a table, use the subscript operator:

a = { 3, foo = 2 }
b = a[1] + a["foo"]

You can store the key in another value and access the table value indirectly:

a = { 3, foo = 2 }
key = foo
b = a[1] + a[key]

And finally, if the key is a string (with no spaces in it), you can use this shorthand:

a = { 3, foo = 2 }
b = a[1] + a.foo -- equivalent to a[1] + a["foo"]

Functions

Lua functions look pretty much like functions in any other language:

a = func( b )

They can return multiple values:

a, b  = func( c )

You can simplify the calling syntax if the function takes a single literal string or a table constructed in place. In that case you don't need to use the enclosing parenthesis around the argument (see §2.5.8 of the Lua manual for more info):

func( "string" ) -- traditional syntax
func "string"    -- simplified syntax

func( { a = 1, b = 2} ) -- traditional syntax
func{ a = 1, b = 2 }    -- simplified syntax