Getting Started with LuaJ

by James Roseborough, Ian Farmer

1 - Simple Examples

Run a script in J2SE

From the main distribution directory line type:

	java -cp luaj-j2se-${VERS}.jar lua src/test/res/test4.lua

You should see the following output:

Compile a script in J2SE

From the main distribution directory line type:

	java -cp luaj-j2se-${VER}.jar luac src/test/res/test4.lua
	java -cp luaj-j2se-${VER}.jar lua luac.out

The compiled output should run and produce the same result.

Run a script in a Java Application

The following pattern is used within J2SE

	import org.luaj.platform.*;
	import org.luaj.vm.*;

	String script = "main.lua";
	Platform.setInstance( new J2sePlatform() );
	LuaState vm = Platform.newLuaState();
	org.luaj.compiler.LuaC.install();
	vm.getglobal( "dofile" );
	vm.pushstring( script );
	vm.call( 1, 0 );

You must include the library lib/luaj-j2se-${VER}.jar in your class path.

A working example may be found in

	src/sample/SampleJ2seMain.java

Additional usage may be found in

	src/sample/LuaRunner.java

Run a script in a MIDlet

The following pattern is used within MIDlets:

	import org.luaj.platform.*;
	import org.luaj.vm.*;

	String script = "main.lua";
	Platform.setInstance( new J2meMidp20Cldc11Platform( midlet ) );
	LuaState vm = Platform.newLuaState();
	org.luaj.compiler.LuaC.install();
	vm.getglobal( "dofile" );
	vm.pushstring( script );
	vm.call( 1, 0 );

The file must be a resource within within the midlet jar for dofile() to find it. Any files included via require() must also be part of the midlet resources.

You must include the library lib/luaj-j2me-${VER}.jar in your midlet jar. They can be obfuscated if desired.

Including the compiler

By default, the compiler is not included to minimize footprint.

To include it, include the following after the Platform is created, but before the script is executed:

	org.luaj.compiler.LuaC.install();

To omit the compiler, omit this line from your startup code.

Run a script using JSR-233 Dynamic Scripting

The standard use of JSR-233 scripting engines may be used:

	ScriptEngineManager mgr = new ScriptEngineManager();
	ScriptEngine e = mgr.getEngineByExtension(".lua");
	e.put("x", 25);
	e.eval("y = math.sqrt(x)");
	System.out.println( "y="+e.get("y") );

All standard aspects of script engines including compiled statements should be supported.

You must include the library lib/luaj-j2se-${VER}.jar in your class path.

A working example may be found in

	src/script/ScriptEngineSample.java

Include and use the luajava library

To include the luajava library, include a line in your script such as:

	require( "org.luaj.lib.j2se.Luajava" )

or include the following line in your startup code:

	org.luaj.lib.j2se.Luajava.init( vm._G );

See the following example for more details:

	src/sample/LuajavaRunner.java

Because reflection is required by the implementation, this is only usable from the J2SE platform.

You must include the library lib/luaj-j2se-${VER}.jar in your class path.

You can try sample code that creates a simple Swing UI using:

	java -cp luaj-j2se-${VERS}.jar lua src/test/res/swingapp.lua

2 - Concepts

Platforms

A Platform is required to set up basic filesystem behavior as well as contolling mappings to underlying math functions.

J2sePlatform

This platform is used to set up the basic environment for a J2SE application. The default search path is the current directory, and the math operations include all those supported by J2SE.

J2mePlatform

This platform is used to set up the basic environment for a J2ME application. The default search path is limited to the jar resources, and the math operations are limited to those supported by J2ME.

Standard Libraries

The following libraries are loaded by default:

	base
	coroutine
	math
	package
	string
	table

See standard lua documentation for details on the library API's

Optional Libraries

A java library may be loaded dynamically if created properly. Currently, there is one such library, luajava.

LuaJava

The luajava library is used to easily bind to Java classes via reflection. It is patterned after the original luajava project.

Unimplemented Libraries

The following libraries are not yet implemented:

	debug
	io

Building the jars

An ant file is included in the root directory which builds the libraries by default.

Other targets exist for creating distribution file an measuring code coverage of unit tests.

Unit tests

A large array of test scripts may be found in

	src/test/res/*.lua

A large set of JUnit tests are invoked by the JUnit 3 suite:

	src/test/java/AllTests.lua

These tests are used for to produce code coverage statistics using build-coverage.xml.