Getting Started with LuaJ

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

introduction · examples · concepts · libraries · luaj api · parser · building · downloads · release notes

1 - Introduction

Goals of Luaj

• Java-centric implementation of lua vm built to leverage standard Java features.
• Lightweight, high performance execution of lua.
• Multi-platform to be able to run on JME, JSE, or JEE environments.
• Complete set of libraries and tools for integration into real-world projects.
• Dependable due to sufficient unit testing of vm and library features.

Luaj version and Lua Versions

Luaj 3.0.x

• _ENV environments model.
• yield from pcall or metatags.
• Bitwise operator library.

• Better thread safety.
• More compatible table behavior.
• Better coroutine-related garbage collection.
• Maven integration.
• Better debug reporting when using closures.
• Line numbers in parse syntax tree.

Luaj 2.0.x

• Support for compiling lua source code into Java source code.
• Support for compiling lua bytecode directly into Java bytecode.
• Stackless vm design centered around dynamically typed objects.
• Good alignment with C API (see names.csv for details)
• Implementation of weak keys and values, and all metatags.

Luaj 1.0.x

Performance

2 - Examples

Run a lua script in Java SE

From the main distribution directory line type:

	java -cp lib/luaj-jse-3.0.1.jar lua examples/lua/hello.lua

You should see the following output:

	hello, world

	java -cp lib/luaj-jse-3.0.1.jar lua examples/lua/swingapp.lua

Links to sources:

	examples/lua/hello.lua
	examples/lua/swingapp.lua

Compile lua source to lua bytecode

From the main distribution directory line type:

	java -cp lib/luaj-jse-3.0.1.jar luac examples/lua/hello.lua
	java -cp lib/luaj-jse-3.0.1.jar lua luac.out

The compiled output "luac.out" is lua bytecode and should run and produce the same result.

Compile lua source or bytecode to java bytecode

Luaj can compile lua sources or binaries directly to java bytecode if the bcel library is on the class path. From the main distribution directory line type:

	ant bcel-lib
	java -cp "lib/luaj-jse-3.0.1.jar;lib/bcel-5.2.jar" luajc -s examples/lua -d . hello.lua
	java -cp "lib/luaj-jse-3.0.1.jar;." lua -l hello

The output hello.class is Java bytecode, should run and produce the same result. There is no runtime dependency on the bcel library, but the compiled classes must be in the class path at runtime, unless runtime jit-compiling via luajc and bcel are desired (see later sections).

Lua scripts can also be run directly in this mode without precompiling using the lua command with the -b option and providing the bcel library in the class path:

	java -cp "lib/luaj-jse-3.0.1.jar;lib/bcel-5.2.jar" lua -b examples/lua/hello.lua

Run a script in a Java Application

A simple hello, world example in luaj is:

	import org.luaj.vm2.*;
	import org.luaj.vm2.lib.jse.*;

	Globals globals = JsePlatform.standardGlobals();
	LuaValue chunk = globals.load("print 'hello, world'");
	chunk.call();
	

	LuaValue chunk = globals.loadfile("examples/lua/hello.lua");

	chunk = globals.load(new StringReader("print 'hello, world'"), "main.lua");

	chunk = globals.load(new FileInputSStream("examples/lua/hello.lua"), "main.lua", "bt"));

A simple example may be found in

	examples/jse/SampleJseMain.java

You must include the library lib/luaj-jse-3.0.1.jar in your class path.

Run a script in a MIDlet

For MIDlets the JmePlatform is used instead:

	import org.luaj.vm2.*;
	import org.luaj.vm2.lib.jme.*;

	Globals globals = JmePlatform.standardGlobals();
	LuaValue chunk = globals.loadfile("examples/lua/hello.lua");
	chunk.call();

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

A simple example may be found in

	examples/jme/SampleMIDlet.java

You must include the library lib/luaj-jme-3.0.1.jar in your midlet jar.

An ant script to build and run the midlet is in

	build-midlet.xml

You must install the wireless toolkit and define WTK_HOME for this script to work.

Run a script using JSR-223 Dynamic Scripting

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

	ScriptEngineManager mgr = new ScriptEngineManager();
	ScriptEngine e = mgr.getEngineByName("luaj");
	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 are supported.

You must include the library lib/luaj-jse-3.0.1.jar in your class path.

A working example may be found in

	examples/jse/ScriptEngineSample.java

	javac -cp lib/luaj-jse-3.0.1.jar examples/jse/ScriptEngineSample.java
	java -cp "lib/luaj-jse-3.0.1.jar;examples/jse" ScriptEngineSample

Excluding the lua bytecode compiler

To exclude the lua-to-lua-bytecode compiler, do not call standardGlobals() or debugGlobals() but instead initialize globals with including only those libraries that are needed and omitting the line:

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

Including the LuaJC lua-bytecode-to-Java-bytecode compiler

To compile from lua to Java bytecode for all lua loaded at runtime, install the LuaJC compiler into a globals object use:

	org.luaj.vm2.jse.luajc.LuaJC.install(globals);

This will compile all lua bytecode into Java bytecode, regardless of if they are loaded as lua source or lua binary files.

The requires bcel to be on the class path, and the ClassLoader of JSE or CDC.

3 - Concepts

Globals

Platform

JsePlatform

Android

Applet

JmePlatform

MIDlet

Thread Safety

• Each thread created by client code must be given its own, distinct Globals instance
• Each thread must not be allowed to access Globals from other threads
• Metatables for Number, String, Thread, Function, Boolean, and and Nil are shared and therefore should not be mutated once lua code is running in any thread.

As an alternative, the JSR-223 scripting interface can be used, and should always provide a separate Globals instance per script engine instance by using a ThreadLocal internally.

Sandboxing

Considerations include

• The debug and luajava library give unfettered access to the luaj vm and java vm so can be abused
• Portions of the os, io, and coroutine libraries are prone to abuse
• Rogue scripts may need to be throttled or killed
• Shared metatables (string, booleans, etc.) need to be made read-only or isolated via class loaders such as LuajClassLoader

• examples/jse/SampleSandboxed.java A java sandbox that limits libraries, limits bytecodes per script, and makes shared tables read-only
• examples/jse/samplesandboxed.lua A lua sandbox that limits librares,limits bytecodes per script, and makes shared tables read-only
• examples/jse/SampleUsingClassLoader.java A heavier but strong sandbox where each script gets its own class loader and a full private luaj implementation

4 - Libraries

Standard Libraries

The following libraries are loaded by both JsePlatform.standardGlobals() and JmePlatform.standardGlobals():

	base
	bit32
	coroutine
	io
	math
	os
	package
	string
	table

The JsePlatform.standardGlobals() globals also include:

	luajava 

The JsePlatform.debugGlobals() and JsePlatform.debugGlobals() functions produce globals that include:

	debug

I/O Library

The JmePlatform.standardGlobals() instantiated the io library io in

	src/jme/org/luaj/vm2/lib/jme/JmeIoLib.java

	src/jse/org/luaj/vm2/lib/jse/JseIoLib.java

OS Library

The basic os library implementation us used by JmePlatform and is in:

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

	src/jse/org/luaj/vm2/lib/jse/JseOsLib.java

Coroutine Library

Luaj uses WeakReferences and the OrphanedThread error to ensure that coroutines that are no longer referenced are properly garbage collected. For thread safety, OrphanedThread should not be caught by Java code. See LuaThread and OrphanedThread javadoc for details. The sample code in examples/jse/CollectingOrphanedCoroutines.java provides working examples.

Debug Library

	require 'org.luaj.vm2.lib.DebugLib'

The Luajava Library

The following lua script will open a swing frame on Java SE:

	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 examples/lua/swingapp.lua for details, including a simple animation loop, rendering graphics, mouse and key handling, and image loading. Or try running it using:

	java -cp lib/luaj-jse-3.0.1.jar lua examples/lua/swingapp.lua

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

The lua connand line tool includes luajava.

5 - LuaJ API

API Javadoc

	 http://luaj.org/luaj/3.0/api

	 ant doc

LuaValue and Varargs

	 org.luaj.vm2.LuaValue

Common Functions

	call();               // invoke the function with no arguments
	call(LuaValue arg1);  // call the function with 1 argument
	invoke(Varargs arg);  // call the function with variable arguments, variable return values
	get(int index);       // get a table entry using an integer key
	get(LuaValue key);    // get a table entry using an arbitrary key, may be a LuaInteger
	rawget(int index);    // raw get without metatable calls
	valueOf(int i);       // return LuaValue corresponding to an integer
	valueOf(String s);    // return LuaValue corresponding to a String
	toint();              // return value as a Java int
	tojstring();          // return value as a Java String
	isnil();              // is the value nil
	NIL;                  // the value nil
	NONE;                 // a Varargs instance with no values	 

Varargs

	 org.luaj.vm2.Varargs

Common Functions

	narg();                 // return number of arguments
	arg1();                 // return the first argument
	arg(int n);             // return the nth argument
	isnil(int n);           // true if the nth argument is nil
	checktable(int n);      // return table or throw error
	optlong(int n,long d);  // return n if a long, d if no argument, or error if not a long

LibFunction

	 org.luaj.vm2.lib.ZeroArgFunction
	 org.luaj.vm2.lib.OneArgFunction
	 org.luaj.vm2.lib.TwoArgFunction
	 org.luaj.vm2.lib.ThreeArgFunction
	 org.luaj.vm2.lib.VarArgFunction

An example of a function with no arguments but a useful return value might be:

	pubic class hostname extends ZeroArgFunction {
		public LuaValue call() {
			return valueOf(java.net.InetAddress.getLocalHost().getHostName());
		}
	}

Calling this function from lua could be done by:

 
	local hostname = require( 'hostname' )

 
	new hostname().call();

Libraries of Java Functions

• The class must be on the class path with name, modname.
• The class must have a public default constructor.
• The class must inherit from LuaFunction.

If luaj can find a class that meets these critera, it will instantiate it, cast it to LuaFunction then call() the instance with two arguments: the modname used in the call to require(), and the environment for that function. The Java may use these values however it wishes. A typical case is to create named functions in the environment that can be called from lua.

A complete example of Java code for a simple toy library is in examples/jse/hyperbolic.java

import org.luaj.vm2.LuaValue;
import org.luaj.vm2.lib.*;

public class hyperbolic extends TwoArgFunction {

	public hyperbolic() {}

	public LuaValue call(LuaValue modname, LuaValue env) {
		LuaValue library = tableOf();
		library.set( "sinh", new sinh() );
		library.set( "cosh", new cosh() );
		env.set( "hyperbolic", library );
		return library;
	}

	static class sinh extends OneArgFunction {
		public LuaValue call(LuaValue x) {
			return LuaValue.valueOf(Math.sinh(x.checkdouble()));
		}
	}
	
	static class cosh extends OneArgFunction {
		public LuaValue call(LuaValue x) {
			return LuaValue.valueOf(Math.cosh(x.checkdouble()));
		}
	}
}

The lua script used to load and test it is in examples/lua/hyperbolicapp.lua

	require 'hyperbolic'

	print('hyperbolic', hyperbolic)
	print('hyperbolic.sinh', hyperbolic.sinh)
	print('hyperbolic.cosh', hyperbolic.cosh)

	print('sinh(0.5)', hyperbolic.sinh(0.5))
	print('cosh(0.5)', hyperbolic.cosh(0.5))

Closures

See the org.luaj.vm2.LuaClosure javadoc for details on using that class directly.

6 - Parser

Javacc Grammar

A plain undecorated grammer that can be used for validation is available in grammar/Lua52.jj while a grammar that generates a typed parse tree is in grammar/LuaParser.jj

Creating a Parse Tree from Lua Source

To simplify the creation of abstract syntax trees from lua sources, the LuaParser class is generated as part of the JME build. To use it, provide an input stream, and invoke the root generator, which will return a Chunk if the file is valid, or throw a ParseException if there is a syntax error.

For example, to parse a file and print all variable names, use code like:

	try {
		String file = "main.lua";
		LuaParser parser = new LuaParser(new FileInputStream(file));
		Chunk chunk = parser.Chunk();
		chunk.accept( new Visitor() {
			public void visit(Exp.NameExp exp) {
				System.out.println("Name in use: "+exp.name.name
					+" line "+exp.beginLine
					+" col "+exp.beginColumn);
			}
		} );
	} catch ( ParseException e ) {
		System.out.println("parse failed: " + e.getMessage() + "\n"
			+ "Token Image: '" + e.currentToken.image + "'\n"
			+ "Location: " + e.currentToken.beginLine + ":" + e.currentToken.beginColumn 
			         + "-" + e.currentToken.endLine + "," + e.currentToken.endColumn);
	}

	examples/jse/SampleParser.java

See the org.luaj.vm2.ast package javadoc for the API relating to the syntax tree that is produced.

7 - Building and Testing

Maven integration

For JSE projects, add this dependency for the luaj-jse jar:

   <dependency>
      <groupId>org.luaj</groupId>
      <artifactId>luaj-jse</artifactId>
      <version>3.0.1</version>
   </dependency>	

   <dependency>
      <groupId>org.luaj</groupId>
      <artifactId>luaj-jme</artifactId>
      <version>3.0.1</version>
   </dependency>	

	examples/maven/pom.xml

Building the jars

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

Unit tests

The main luaj JUnit tests are organized into a JUnit 3 suite:

	test/junit/org/luaj/vm2/AllTests.lua

Unit test scripts can be found in these locations

	test/lua/*.lua
	test/lua/errors/*.lua
	test/lua/perf/*.lua
	test/lua/luaj3.0.1-tests.zip

Code coverage

A build script for running unit tests and producing code coverage statistics is in

	build-coverage.xml

8 - Downloads

Downloads and Project Pages

	SourceForge Luaj Project Page
	SourceForge Luaj Download Area

The jar files may also be downloaded from the maven central repository, see Maven Integration.

Files are no longer hosted at LuaForge.

9 - Release Notes

Main Changes by Version

Known Issues

Limitations

• debug code may not be completely removed by some obfuscators
• tail calls are not tracked in debug information
• mixing different versions of luaj in the same java vm is not supported
• values associated with weak keys may linger longer than expected
• behavior of luaj when a SecurityManager is used has not been fully characterized
• negative zero is treated as identical to integer value zero throughout luaj
• lua compiled into java bytecode using luajc cannot use string.dump() or xpcall()
• number formatting with string.format() is not supported
• shared metatables for string, bool, etc are shared across Globals instances in the same class loader
• orphaned threads will not be collected unless garbage collection is run and sufficient time elapses

File Character Encoding

• supplying a Reader to Globals.load() is preferred over InputStream variants
• using FileReader or InputStreamReader to get the default OS encoding should work in most cases
• string literals with quoted characters may not produce the expected values in generated code
• command-line tools lua, luac, and luajc will require -c Cp037 to specify the encoding