Getting Started with LuaJ

Copyright © 2007-2009 Luaj.org. Freely available under the terms of the Luaj license.

examples · concepts · libraries · building · downloads · release notes

1 - Simple Examples

Run a script in J2SE

From the main distribution directory line type:

	java -cp lib/luaj-j2se-1.0.jar lua src/test/res/test4.lua

You should see the following output:

	40

Compile a script in J2SE

From the main distribution directory line type:

	java -cp lib/luaj-j2se-1.0.jar luac src/test/res/test4.lua
	java -cp lib/luaj-j2se-1.0.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-1.0.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-1.0.jar in your midlet jar. They can be obfuscated if desired.

Including the compiler

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-1.0.jar in your class path.

A working example may be found in

	src/script/ScriptEngineSample.java

2 - Concepts

Platforms

J2sePlatform

J2mePlatform

3 - Libraries

Standard Libraries

The following libraries are loaded by default in J2ME and J2SE platforms:

	base
	coroutine
	math
	package
	string
	table

The following libraries are optional, but preconfigured for some platforms and tools:

           
	io
	os
	debug     
	luajava 

Optional Libraries

I/O Library

The J2ME platform has an optional, partial implementation of the io in

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

	LuaState vm = Platform.newLuaState();
	org.luaj.lib.j2me.Cldc10IoLib.install(vm._G);

See the sample midlet int src/sample/SampleMIDlet for an example.

OS Library

	src/core/org/luaj/lib/OsLib.java

	src/j2se/org/luaj/lib/j2se/J2seOsLib.java

Debug Library

	debug

	LuaState vm = Platform.newLuaState();
	org.luaj.lib.DebugLib.install(vm);

	require 'org.luaj.lib.DebugLib'

The Luajava Library

The following lua script will open a swiing frame on J2SE:

	jframe = luajava.bindClass( "javax.swing.JFrame" )
	frame = luajava.newInstance( "javax.swing.JFrame", "Texts" );
	frame:setDefaultCloseOperation(jframe.EXIT_ON_CLOSE)
	frame:setSize(300,400)
	frame:setVisible(true)

See a longer sample in src/test/res/swingapp.lua for details, or try running it using:

	java -cp lib/luaj-j2se-1.0.jar lua src/test/res/swingapp.lua

The J2ME platform does not include this library, and it cannot be made to work because of the lack of a reflection API in J2SE.

4 - Building and Testing

Building the jars

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.

5 - Downloads

Downloads and Project Pages

	SourceForge Luaj Project Page
	SourceForge Luaj Download Area

and LuaForge:

	LuaForge Luaj Project Page
	LuaForge Luaj Project Area

6 - Release Notes