Copyright © 2009-2013 Luaj.org. Freely available under the terms of the Luaj license.
introduction · examples · concepts · libraries · luaj api · parser · building · downloads · release notes
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
From the main distribution directory line type:
java -cp lib/luaj-jse-3.0-beta1.jar lua examples/lua/hello.lua
You should see the following output:
hello, worldTo see how luaj can be used to acccess most Java API's including swing, try:
java -cp lib/luaj-jse-3.0-beta1.jar lua examples/lua/swingapp.lua
From the main distribution directory line type:
java -cp lib/luaj-jse-3.0-beta1.jar luac examples/lua/hello.lua java -cp lib/luaj-jse-3.0-beta1.jar lua luac.out
The compiled output "luac.out" is lua bytecode and should run and produce the same result.
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-beta1.jar;lib/bcel-5.2.jar" luajc -s examples/lua -d . hello.lua java -cp "lib/luaj-jse-3.0-beta1.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-beta1.jar;lib/bcel-5.2.jar" lua -b examples/lua/hello.lua
The following pattern is used within Java SE
import org.luaj.vm2.*;
import org.luaj.vm2.lib.jse.*;
String script = "examples/lua/hello.lua";
LuaValue _G = JsePlatform.standardGlobals();
_G.get("dofile").call( LuaValue.valueOf(script) );
A simple example may be found in
examples/jse/SampleJseMain.java
You must include the library lib/luaj-jse-3.0-beta1.jar in your class path.
The for MIDlets the JmePlatform is used instead:
import org.luaj.vm2.*;
import org.luaj.vm2.lib.jme.*;
String script = "examples/lua/hello.lua";
LuaValue _G = JmePlatform.standardGlobals();
_G.get("dofile").call( LuaValue.valueOf(script) );
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
examples/jme/SampleMIDlet.java
You must include the library lib/luaj-jme-3.0-beta1.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.
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 should be supported.
You must include the library lib/luaj-jse-3.0-beta1.jar in your class path.
A working example may be found in
examples/jse/ScriptEngineSample.javaTo compile and run it using Java 1.6 or higher:
javac -cp lib/luaj-jse-3.0-beta1.jar examples/jse/ScriptEngineSample.java java -cp "lib/luaj-jse-3.0-beta1.jar;examples/jse" ScriptEngineSample
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();
To compile from lua to Java bytecode for all lua loaded at runtime, install the LuaJC compiler after globals have been created using:
org.luaj.vm2.jse.luajc.LuaJC.install();
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.
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.
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
The JmePlatform.standardGlobals() instantiated the io library io in
src/jme/org/luaj/vm2/lib/jme/JmeIoLib.javaThe JsePlatform.standardGlobals() includes support for random access and is in
src/jse/org/luaj/vm2/lib/jse/JseIoLib.java
The basic os library implementation us used by JmePlatform and is in:
src/core/org/luaj/lib/OsLib.javaA richer version for use by JsePlatform is :
src/jse/org/luaj/vm2/lib/jse/JseOsLib.javaTime is a represented as number of milliseconds since the epoch, and most time and date formatting, locales, and other features are not implemented.
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.
require 'org.luaj.vm2.lib.DebugLib'The lua command line utility includes the debug library by default.
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-beta1.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.
http://luaj.sourceforge.net/api/3.0You can also build a local version from sources using
ant doc
org.luaj.vm2.LuaValue
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
org.luaj.vm2.Varargs
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 longSee the Varargs API for a complete list.
org.luaj.vm2.lib.ZeroArgFunction org.luaj.vm2.lib.OneArgFunction org.luaj.vm2.lib.TwoArgFunction org.luaj.vm2.lib.ThreeArgFunction org.luaj.vm2.lib.VarArgFunctionEach of these functions has an abstract method that must be implemented, and argument fixup is done automatically by the classes as each Java function is invoked.
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());
}
}
The value env is the environment of the function, and is normally supplied
by the instantiating object whenever default loading is used.
Calling this function from lua could be done by:
local hostname = require( 'hostname' )while calling this function from Java would look like:
new hostname().call();Note that in both the lua and Java case, extra arguments will be ignored, and the function will be called. Also, no virtual machine instance is necessary to call the function. To allow for arguments, or return multiple values, extend one of the other base classes.
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()));
}
}
}
In this case the call to require invokes the library itself to initialize it. The library implementation
puts entries into a table, and stores this table in the environment.
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))
For this example to work the code in hyperbolic.java must be compiled and put on the class path.
See the org.luaj.vm2.LuaClosure javadoc for details on using that class directly.
A plain undecorated grammer that can be used for validation is available in grammar/Lua51.jj while a grammar that generates a typed parse tree is in grammar/LuaParser.jj
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);
}
An example that prints locations of all function definitions in a file may be found in
examples/jse/SampleParser.java
See the org.luaj.vm2.ast package javadoc for the API relating to the syntax tree that is produced.
For JSE projects, add this dependency for the luaj-jse jar:
<dependency>
<groupId>org.luaj</groupId>
<artifactId>luaj-jse</artifactId>
<version>3.0-beta1</version>
</dependency>
while for JME projects, use the luaj-jme jar:
<dependency>
<groupId>org.luaj</groupId>
<artifactId>luaj-jme</artifactId>
<version>3.0-beta1</version>
</dependency>
An example skelton maven pom file for a skeleton project is in
examples/maven/pom.xml
Other targets exist for creating distribution file an measuring code coverage of 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-tests.zip
A build script for running unit tests and producing code coverage statistics is in
build-coverage.xmlIt relies on the cobertura code coverage library.
SourceForge Luaj Project Page SourceForge Luaj Download AreaFiles are no longer hosted at LuaForge.
|