<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>Getting Started with LuaJ</title>
<link rel="stylesheet" type="text/css" href="http://sourceforge.net/dbimage.php?id=196140">
<link rel="stylesheet" type="text/css" href="http://sourceforge.net/dbimage.php?id=196141">
<META HTTP-EQUIV="content-type" CONTENT="text/html; charset=iso-8859-1">
</head>
<body>
<hr>
<h1>
<a href="README.html"><img src="http://sourceforge.net/dbimage.php?id=196139" alt="" border="0"></a>
Getting Started with LuaJ
</h1>
by James Roseborough, Ian Farmer
<p>
<small>
Copyright © 2007-2009 Luaj.org.
Freely available under the terms of the
<a href="http://sourceforge.net/dbimage.php?id=196142">Luaj license</a>.
</small>
<hr>
<p>
<a href="#1">examples</a>
·
<a href="#2">concepts</a>
·
<a href="#3">libraries</a>
·
<a href="#4">building</a>
·
<a href="#5">downloads</a>
<!-- ====================================================================== -->
<p>
<h1>1 - <a name="1">Simple Examples</a></h1>
<h2>Run a script in J2SE</h2>
<p>
From the main distribution directory line type:
<pre>
java -cp luaj-j2se-${VERS}.jar lua src/test/res/test4.lua
</pre>
<p>
You should see the following output:
<pre>
40
</pre>
<h2>Compile a script in J2SE</h2>
<p>
From the main distribution directory line type:
<pre>
java -cp luaj-j2se-${VER}.jar luac src/test/res/test4.lua
java -cp luaj-j2se-${VER}.jar lua luac.out
</pre>
<p>
The compiled output should run and produce the same result.
<h2>Run a script in a Java Application</h2>
<p>
The following pattern is used within J2SE
<pre>
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 );
</pre>
<p>
A simple example may be found in
<pre>
src/sample/SampleJ2seMain.java
</pre>
<p>
You must include the library <b>lib/luaj-j2se-${VER}.jar</b> in your class path.
<h2>Run a script in a MIDlet</h2>
<p>
The following pattern is used within MIDlets:
<pre>
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 );
</pre>
<p>
The file must be a resource within within the midlet jar for <em>dofile()</em> to find it.
Any files included via <em>require()</em> must also be part of the midlet resources.
<p>
A simple example may be found in
<pre>
src/sample/SampleMIDlet.java
</pre>
<p>
You must include the library <b>lib/luaj-j2me-${VER}.jar</b> in your midlet jar.
They can be obfuscated if desired.
<h2>Including the compiler</h2>
By default, the compiler is not included to minimize footprint.
<p>
To include it, include the following after the Platform is created,
but before the script is executed:
<pre>
org.luaj.compiler.LuaC.install();
</pre>
<p>
To omit the compiler, omit this line from your startup code.
<h2>Run a script using JSR-233 Dynamic Scripting</h2>
<p>
The standard use of JSR-233 scripting engines may be used:
<pre>
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") );
</pre>
<p>
All standard aspects of script engines including compiled statements should be supported.
<p>
You must include the library <b>lib/luaj-j2se-${VER}.jar</b> in your class path.
<p>
A working example may be found in
<pre>
src/script/ScriptEngineSample.java
</pre>
<h1>2 - <a name="2">Concepts</a></h1>
<h2>Platforms</h2>
A Platform is required to set up basic filesystem behavior as well as
contolling mappings to underlying math functions.
<h3>J2sePlatform</h3>
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.
<h3>J2mePlatform</h3>
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.
<h1>3 - <a name="3">Libraries</a></h1>
<h2>Standard Libraries</h2>
Libraries are coded to closely match the behavior specified in
See <a href="http://www.lua.org/manual/5.1/">standard lua documentation</a> for details on the library API's
<p>
The following libraries are loaded by default in J2ME and J2SE platforms:
<pre>
base
coroutine
math
package
string
table
</pre>
<p>
The following libraries are optional, but preconfigured for some platforms and tools:
<pre>
io
os
debug
luajava
</pre>
<h2>Optional Libraries</h2>
<h3>I/O Library</h3>
The J2SE platform contains the <em>io</em> library by default.
<p>
The J2ME platform has an optional, partial implementation of the <em>io</em> in
<pre>
src/j2me/org/luaj/lib/j2me/Cldc10IoLib.java
</pre>
To install into your vm instance use (j2me only):
<pre>
LuaState vm = Platform.newLuaState();
org.luaj.lib.j2me.Cldc10IoLib.install(vm._G);
</pre>
<p>
See the sample midlet int <em>src/sample/SampleMIDlet</em> for an example.
<h3>OS Library</h3>
A basic os library implementation for either J2ME or J2SE is provided ins
<pre>
src/core/org/luaj/lib/OsLib.java
</pre>
A slightly more complete version for J2SE is in:
<pre>
src/j2se/org/luaj/lib/j2se/J2seOsLib.java
</pre>
Time is a represented as number of milliseconds since the epoch,
and most time and date formatting, locales, and other features
are not implemented.
<h3>Debug Library</h3>
The following library is optional:
<pre>
debug
</pre>
Install from Java using:
<pre>
LuaState vm = Platform.newLuaState();
org.luaj.lib.DebugLib.install(vm);
</pre>
or install from lua using</em>:
<pre>
require 'org.luaj.lib.DebugLib'
</pre>
The <em>lua</em> command line utility includes the debug library by default.
<h3>The Luajava Library</h3>
The J2SE platform includes the <em>luajava</em> library, which simplifies binding to Java classes and methods.
It is patterned after the original <a href="http://www.keplerproject.org/luajava/">luajava project</a>.
<p>
The following lua script will open a swiing frame on J2SE:
<pre>
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)
</pre>
<p>
See a longer sample in <em>src/test/res/swingapp.lua</em> for details, or try running it using:
<pre>
java -cp luaj-j2se-${VERS}.jar lua src/test/res/swingapp.lua
</pre>
<p>
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.
<h1>4 - <a name="4">Building and Testing</a></h1>
<h2>Building the jars</h2>
An ant file is included in the root directory which builds the libraries by default.
<p>
Other targets exist for creating distribution file an measuring code coverage of unit tests.
<h2>Unit tests</h2>
<p>
A large array of test scripts may be found in
<pre>
src/test/res/*.lua
</pre>
<p>
A large set of JUnit tests are invoked by the JUnit 3 suite:
<pre>
src/test/java/AllTests.lua
</pre>
<p>
These tests are used for to produce code coverage statistics using build-coverage.xml.
<h1>5 - <a name="5">Downloads</a></h1>
<h2>Downloads and Project Pages</h2>
Downloads are currently hosted on SourceForge
<br/>
<pre>
<a href="http://luaj.sourceforge.net/">SourceForge Luaj Project Page</a>
<a href="http://sourceforge.net/project/platformdownload.php?group_id=197627">SourceForge Luaj Download Area</a>
</pre>
<p/>
and LuaForge:
<pre>
<a href="http://luaforge.net/projects/luaj/">LuaForge Luaj Project Page</a>
<a href="http://luaforge.net/frs/?group_id=457">LuaForge Luaj Project Area</a>
</pre>