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 );

A simple example may be found in

	src/sample/SampleJ2seMain.java

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

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.

A simple example may be found in

	src/sample/SampleMIDlet.java

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 in J2ME and J2SE platforms:

	base
	coroutine
	math
	package
	string
	table

In addition, J2SE contains these two libraries:

	io
	luajava

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

There is a partial implementation of the io for J2ME in

	src/j2me/org/luaj/lib/j2me/Cldc10IoLib.java

See the sample midlet to see how it is added to a platform.

The Luajava Library

The luajava library implements a few functions which allow access to most classes within the host J2SE runtime. They are included as part of the standard J2SE platform.

LuaJava

The luajava library is used to easily bind to Java classes via reflection. It is patterned after the original luajava project. Because J2ME does not contain a reflection API, this library cannot be made to work on J2ME, and is not included by default.

Unimplemented Libraries

The following libraries are not yet implemented:

	os
	debug

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.