Lua

From TargetWiki

Most of Targetware can be scripted with a programming language called Lua.

Contents 1 Learning Lua 2 Standard Libraries 3 Files and Directories 4 Error Handling 5 Tables and Configuration Files 6 Gotchas

Learning Lua

These sites are useful for learning about the Lua Programming Language:

• http://www.lua.org/
• http://www.lua.org/pil/
• http://www.lua.org/manual/5.1/
• http://lua-users.org/wiki/TutorialDirectory
• http://lua-users.org/wiki/SampleCode

Standard Libraries

In the Targetware environment, all of the Lua standard libraries (other than the 'debug' library) are included. There are a few functions that have been removed, for security reasons. These are:

io.popen()

Removed because Targetware scripts should not be allowed to start other programs.

io.tmpfile()

Removed because Targetware scripts can only manipulate files in the data root and the preferences root.

os.execute()

Removed to prevent Targetware scripts from running arbitrary system commands.

os.exit()

Removed to prevent Targetware scripts from arbitrarly shutting down Targetware.

os.getenv()

Removed because Targetware scripts should not depend on or have access to environment variables.

os.setlocal()

Removed to prevent Targetware scripts from altering the system locale.

os.tmpname()

Removed for the same reason as io.tmpfile().

package.loadlib()

Removed to prevent Targetware scripts from loading arbitrary C libraries. In addition, require will load only Lua scripts, and not C libraries.

Files and Directories

The root of the Lua script environment is the Targetware data directory. All filenames are specified in TW style, with / as the directory separator. In addition, Targetware extends Lua with some directory handling commands:

pushdir( <string> or <root indicator> )

This changes the current directory to the specified directory in the current root if passed a string. A root indicator can also be passed, to change to the selected root directory. This indicator can be either DATAROOT or PREFROOT.

popdir()

Pops one directory change, returning to whatever directory was the current directory before.

opendir( <directory>, <extension> )

Both arguments are optional. If specified, the first argument indicates the directory to open. If ommitted, the current directory will be opened. The current directory can also be specified as ".", and the parent directory as "..". The second argument, if supplied, will limit the returned contents to only files with the specified file extension. The return value is a table with each file in the specified directory listed as a key (not a value), and the value for each entry being false if the entry is a file and true if the entry is a directory. Directories will only be included if no file extension is specified.

Error Handling

Targetware also adds some error handling and monitoring functions to Lua.

errorhandler()

This returns the Lua function that your script has set as the local error handler. See the next function for a description of this.

seterrorhandler( <function> )

This takes a single argument, which is a Lua function. That function will be called any time Targetware attempts a callback into your script and encounters an execution error. Your error handling function will receive a single argument, which is a string describing the error. It can take any action it needs to, and should then return a string describing the error to Targetware - this can be the same string, or an altered one.

errorlog( <string> )

This will write the string passed to it to the Targetware log file.

Tables and Configuration Files

Targetware uses a standard configuration file format that mirrors the layout of Lua tables. To support reading and writing these configuration files, two new functions have been added to the table library:

table.read( <filename> )

This returns a Lua table whose contents are the same as the configuration file specified. If there is no such file, or if the file isn't a valid configuration file, this function returns nil.

table.write( <Lua table>, <filename> )

This writes the specified Lua table to the specified configuration file, replacing any file that's currently there. A configuration file can only support keys in a Lua table that are either numbers or strings, and can only support values that are nil, booleans, numbers, strings, or other tables.

Gotchas

It is very important to note that all indexing functions are Lua style, not C style, so the first element is 1, not 0.