open-autonomous-connection/luaj
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 2 Wiki Activity

Initial sources for planned 2.0 luaj vm release. Most interpreter features and library functions working.

Browse Source
This commit is contained in:
James Roseborough
2009-10-27 06:12:24 +00:00
parent d16fad00e8
commit 3863ff8e46
116 changed files with 33600 additions and 122 deletions
Download Patch File Download Diff File Expand all files Collapse all files

144
README.html
View File

@@ -17,7 +17,7 @@
Getting Started with LuaJ
</h1>
James Roseborough, Ian Farmer, Version 1.0.1
James Roseborough, Ian Farmer, Version 1.9.50
<p>
<small>
Copyright &copy; 2007-2009 Luaj.org.
@@ -41,32 +41,36 @@ Freely available under the terms of the
<!-- ====================================================================== -->
<p>
<font color=#800000><em>
This is a development release for a planned luaj 2.0. The most recent stable release is 1.0.1
</em></font>
<h1>1 - <a name="1">Simple Examples</a></h1>
<h2>Run a script in J2SE</h2>
<h2>Run a script in Java SE</h2>
<p>
From the main distribution directory line type:
<pre>
java -cp lib/luaj-j2se-1.0.jar lua src/test/res/test4.lua
java -cp lib/luaj-jse-1.9.50.jar lua examples/lua/hello.lua
</pre>
<p>
You should see the following output:
<pre>
40
hello, world
</pre>
<h2>Compile a script in J2SE</h2>
<h2>Compile a script in Java SE</h2>
<p>
From the main distribution directory line type:
<pre>
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
java -cp lib/luaj-jse-1.0.jar luac examples/lua/hello.lua
java -cp lib/luaj-jse-1.0.jar lua luac.out
</pre>
<p>
@@ -75,29 +79,27 @@ 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
The following pattern is used within Java SE
<pre>
import org.luaj.platform.*;
import org.luaj.vm.*;
import org.luaj.vm2.*;
import org.luaj.vm2.lib.*;
import org.luaj.vm2.compiler.LuaC;
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 );
String script = "examples/lua/hello.lua";
LuaC.install();
LuaValue _G = JsePlatform.standardGlobals();
_G.get("dofile").call( LuaValue.valueOf(script) );
</pre>
<p>
A simple example may be found in
<pre>
src/sample/SampleJ2seMain.java
examples/jse/SampleJseMain.java
</pre>
<p>
You must include the library <b>lib/luaj-j2se-1.0.jar</b> in your class path.
You must include the library <b>lib/luaj-jse-1.9.50.jar</b> in your class path.
<h2>Run a script in a MIDlet</h2>
@@ -105,16 +107,14 @@ You must include the library <b>lib/luaj-j2se-1.0.jar</b> in your class path.
The following pattern is used within MIDlets:
<pre>
import org.luaj.platform.*;
import org.luaj.vm.*;
import org.luaj.vm2.*;
import org.luaj.vm2.lib.*;
import org.luaj.vm2.compiler.LuaC;
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 );
String script = "examples/lua/hello.lua";
LuaC.install();
LuaValue _G = JmePlatform.standardGlobals();
_G.get("dofile").call( LuaValue.valueOf(script) );
</pre>
<p>
@@ -124,22 +124,23 @@ Any files included via <em>require()</em> must also be part of the midlet resour
<p>
A simple example may be found in
<pre>
src/sample/SampleMIDlet.java
examples/jme/SampleMIDlet.java
</pre>
<p>
You must include the library <b>lib/luaj-j2me-1.0.jar</b> in your midlet jar.
You must include the library <b>lib/luaj-jme-1.9.50.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.
By default, the compiler is not included so as to minimize footprint.
Without a compiler, files can still be executed, but they must be compiled elsewhere beforehand.
The "luac" utility is provided in the jse jar for this purpose, or a standard lua compiler can be used.
<p>
To include it, include the following after the Platform is created,
but before the script is executed:
To include the Java it, include the following sometime before lua source files are loaded:
<pre>
org.luaj.compiler.LuaC.install();
org.luaj.vm2.compiler.LuaC.install();
</pre>
<p>
@@ -162,32 +163,35 @@ The standard use of JSR-233 scripting engines may be used:
All standard aspects of script engines including compiled statements should be supported.
<p>
You must include the library <b>lib/luaj-j2se-1.0.jar</b> in your class path.
You must include the library <b>lib/luaj-jse-1.9.50.jar</b> in your class path.
<p>
A working example may be found in
<pre>
src/script/ScriptEngineSample.java
examples/jse/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.
<h2>Globals</h2>
The old notion of platform has been replaced with creation of globals.
Two classes are provided to encapsulate common combinations of libraries.
<h3>J2sePlatform</h3>
<h3>JsePlatform</h3>
This platform is used to set up the basic environment for a J2SE application.
This class can be used as a factory for globals in a typical Java SE application.
All standard libraries are included, as well as the luajava library.
The default search path is the current directory,
and the math operations include all those supported by J2SE.
and the math operations include all those supported by Java SE.
<h3>J2mePlatform</h3>
<h3>JmePlatform</h3>
This platform is used to set up the basic environment for a J2ME application.
This class can be used to set up the basic environment for a Java ME application.
The default search path is limited to the jar resources,
and the math operations are limited to those supported by J2ME.
and the math operations are limited to those supported by Java ME.
All libraries are included except luajava, and the os, io, and math libraries are
limited to those functions that can be supported on that platform.
<h1>3 - <a name="3">Libraries</a></h1>
@@ -198,7 +202,7 @@ 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:
The following libraries are loaded by default in Java ME and Java SE platforms:
<pre>
base
coroutine
@@ -220,32 +224,23 @@ The following libraries are optional, but preconfigured for some platforms and t
<h2>Optional Libraries</h2>
<h3>I/O Library</h3>
The J2SE platform contains the <em>io</em> library by default.
The Java SE platform contains the <em>io</em> library by default.
<p>
The J2ME platform has an optional, partial implementation of the <em>io</em> in
The Java ME platform has an optional, partial implementation of the <em>io</em> in
<pre>
src/j2me/org/luaj/lib/j2me/Cldc10IoLib.java
src/jme/org/luaj/vm2/lib/jme/JmeIoLib.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
A basic os library implementation for either Java ME or Java SE is provided ins
<pre>
src/core/org/luaj/lib/OsLib.java
</pre>
A slightly more complete version for J2SE is in:
A slightly more complete version for Java SE is in:
<pre>
src/j2se/org/luaj/lib/j2se/J2seOsLib.java
src/jse/org/luaj/vm2/lib/jse/JseOsLib.java
</pre>
Time is a represented as number of milliseconds since the epoch,
@@ -260,24 +255,23 @@ The following library is optional:
Install from Java using:
<pre>
LuaState vm = Platform.newLuaState();
org.luaj.lib.DebugLib.install(vm);
org.luaj.vm2.lib.DebugLib.install(vm);
</pre>
or install from lua using</em>:
<pre>
require 'org.luaj.lib.DebugLib'
require 'org.luaj.vm2.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.
The Java SE 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:
The following lua script will open a swiing frame on Java SE:
<pre>
jframe = luajava.bindClass( "javax.swing.JFrame" )
frame = luajava.newInstance( "javax.swing.JFrame", "Texts" );
@@ -289,11 +283,11 @@ The following lua script will open a swiing frame on J2SE:
<p>
See a longer sample in <em>src/test/res/swingapp.lua</em> for details, or try running it using:
<pre>
java -cp lib/luaj-j2se-1.0.jar lua src/test/res/swingapp.lua
java -cp lib/luaj-jse-1.9.50.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.
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 SE.
<h1>4 - <a name="4">Building and Testing</a></h1>
@@ -308,13 +302,13 @@ Other targets exist for creating distribution file an measuring code coverage of
<p>
A large array of test scripts may be found in
<pre>
src/test/res/*.lua
test/lua/*.lua
</pre>
<p>
A large set of JUnit tests are invoked by the JUnit 3 suite:
<pre>
src/test/java/AllTests.lua
test/junit/org/luaj/vm2/AllTests.lua
</pre>
<p>
@@ -323,7 +317,9 @@ These tests are used for to produce code coverage statistics using build-coverag
<h1>5 - <a name="5">Downloads</a></h1>
<h2>Downloads and Project Pages</h2>
Downloads are currently hosted on SourceForge
Downloads for version 1.0.1 are currently hosted on SourceForge.
Downloads of built packages for 2.0 are not yet available.
Sources are available via sourceforge.net
<br/>
<pre>
<a href="http://luaj.sourceforge.net/">SourceForge Luaj Project Page</a>
@@ -340,7 +336,5 @@ and LuaForge:
Main changes by version:
<table cellspacing="10"><tr><td><table cellspacing="4">
<tr valign="top"><td>&nbsp;&nbsp;<b>1.0</b></td><td>Initial publicly supported release.</td></tr>
<tr valign="top"><td>&nbsp;&nbsp;<b>1.0.1</b></td><td>Fix arg check and behavior of xpcall() to leave stack intact.
Fix debug.sethook() to when called from hook function. Fix debug.gethook() return values. Array support in luajava bindings.</td></tr>
</table></td></tr></table>
<tr valign="top"><td>&nbsp;&nbsp;<b>1.9.50</b></td><td>Most interpreter features are working. Initial port of all libraries has been done.</td></tr>
</table>