This is a fork!

<div style="border: 1px dotted red; margin: 1.em 0.5em; font-weight: bold; color: red;"> This repository has been forked from the original CVS sources of Luaj. The commit history has been converted to make sure that the original work of James Roseborough and Ian Farmer is not lost. Unfortunately, I was not able to contact either James or Ian to hand over ownership of the Github organization/repo as I have originally intended to. The community however seems interested enough to continue work on the original sources and therefore I have decided to make sure that any useful pull requests that may add some value to the original code base shall be merged in from now on.<br> -- Benjamin P. Jung, Jan. 26th 2018 </div> <h1>Getting Started with LuaJ</h1> James Roseborough, Ian Farmer, Version 3.0.2 <p> <small> Copyright &copy; 2009-2014 Luaj.org. Freely available under the terms of the <a href="LICENSE">Luaj license</a>. </small> <hr> <p>

<a href="#1">introduction</a> · <a href="#2">examples</a> · <a href="#3">concepts</a> · <a href="#4">libraries</a> · <a href="#5">luaj api</a> · <a href="#6">parser</a> · <a href="#7">building</a> · <a href="#8">downloads</a> · <a href="#9">release notes</a>

<!-- ====================================================================== --> <p> <h1>1 - <a name="1">Introduction</a></h1> <h2>Goals of Luaj</h2> Luaj is a lua interpreter based on the 5.2.x version of lua with the following goals in mind: <ul> <li>Java-centric implementation of lua vm built to leverage standard Java features. <li>Lightweight, high performance execution of lua. <li>Multi-platform to be able to run on JME, JSE, or JEE environments. <li>Complete set of libraries and tools for integration into real-world projects. <li>Dependable due to sufficient unit testing of vm and library features. </ul> <h2>Luaj version and Lua Versions</h2> <h3>Luaj 3.0.x</h3> Support for lua 5.2.x features: <ul> <li>_ENV environments model. <li>yield from pcall or metatags. <li>Bitwise operator library. </ul> It also includes miscellaneous improvements over luaj 2.0.x: <ul> <li>Better thread safety. <li>More compatible table behavior. <li>Better coroutine-related garbage collection. <li>Maven integration. <li>Better debug reporting when using closures. <li>Line numbers in parse syntax tree. </ul> <h3>Luaj 2.0.x</h3> Support for lua 5.1.x features, plus: <ul> <li>Support for compiling lua source code into Java source code. <li>Support for compiling lua bytecode directly into Java bytecode. <li>Stackless vm design centered around dynamically typed objects. <li>Good alignment with C API (see <a href="names.csv">names.csv</a> for details) <li>Implementation of weak keys and values, and all metatags. </ul> <h3>Luaj 1.0.x</h3> Support for most lua 5.1.x features. <h2>Performance</h2> Good performance is a major goal of luaj. The following table provides measured execution times on a subset of benchmarks from <a href="http://shootout.alioth.debian.org/">the computer language benchmarks game</a> in comparison with the standard C distribution. <table cellspacing="10"><tr><td><table> <tr valign="top"> <td><u>Project</td> <td><u>Version</td> <td><u>Mode</td> <td rowspan="9">&nbsp;&nbsp;</td> <td colspan="4" align="center"><u>Benchmark&nbsp;execution&nbsp;time&nbsp;(sec)</td> <td rowspan="9">&nbsp;&nbsp;</td> <td><u>Language</td> <td><u>Sample&nbsp;command</td> </tr> <tr valign="top"> <td colspan="2"></td> <td></td> <td><em>binarytrees 15</em></td> <td><em>fannkuch 10</em></td> <td><em>nbody 1e6</em></td> <td><em>nsieve 9</em></td> </tr> <tr valign="top"> <td>luaj</td> <td>3.0</td> <td>-b (luajc)</td> <td>2.980</td> <td>5.073</td> <td>16.794</td> <td>11.274</td> <td>Java</td> <td>java -cp luaj-jse-3.0.2.jar;bcel-5.2.jar lua <b>-b</b> fannkuch.lua 10</td></tr> <tr valign="top"> <td></td> <td></td> <td>-n (interpreted)</td> <td>12.838</td> <td>23.290</td> <td>36.894</td> <td>15.163</td> <td></td> <td>java -cp luaj-jse-3.0.2.jar lua -n fannkuch.lua 10</td></tr> <tr valign="top"> <td>lua</td> <td>5.1.4</td> <td></td> <td>17.637</td> <td>16.044</td> <td>15.201</td> <td>5.477</td> <td>C</td> <td>lua fannkuch.lua 10</td></tr> <tr valign="top"> <td>jill</td> <td>1.0.1</td> <td></td> <td>44.512</td> <td>54.630</td> <td>72.172</td> <td>20.779</td> <td>Java</td> <td></td></tr> <tr valign="top"> <td>kahlua</td> <td>1.0</td> <td>jse</td> <td>22.963</td> <td>63.277</td> <td>68.223</td> <td>21.529</td> <td>Java</td> <td></td></tr> <tr valign="top"> <td>mochalua</td> <td>1.0</td> <td></td> <td>50.457</td> <td>70.368</td> <td>82.868</td> <td>41.262</td> <td>Java</td> <td></td></tr> </table></td></tr></table>

Luaj in interpreted mode performs well for the benchmarks, and even better when the lua-to-java-bytecode (luajc) compiler is used, and actually executes <em>faster</em> than C-based lua in some cases.
It is also faster than Java-lua implementations Jill, Kahlua, and Mochalua for all benchmarks tested.

<h1>2 - <a name="2">Examples</a></h1> <h2>Run a lua script in Java SE</h2> <p> From the main distribution directory line type: <pre> java -cp luaj-jse-3.0.2.jar lua examples/lua/hello.lua </pre> <p> You should see the following output: <pre> hello, world </pre>

To see how luaj can be used to acccess most Java API's including swing, try:

<pre> java -cp luaj-jse-3.0.2.jar lua examples/lua/swingapp.lua </pre> <p> Links to sources:<pre> <a href="examples/lua/hello.lua">examples/lua/hello.lua</a> <a href="examples/lua/swingapp.lua">examples/lua/swingapp.lua</a> </pre> <h2>Compile lua source to lua bytecode</h2> <p> From the main distribution directory line type: <pre> java -cp luaj-jse-3.0.2.jar luac examples/lua/hello.lua java -cp luaj-jse-3.0.2.jar lua luac.out </pre> <p> The compiled output "luac.out" is lua bytecode and should run and produce the same result. <h2>Compile lua source or bytecode to java bytecode</h2> <p> 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: <pre> ant bcel-lib java -cp &quot;luaj-jse-3.0.2.jar;lib/bcel-5.2.jar&quot; luajc -s examples/lua -d . hello.lua java -cp &quot;luaj-jse-3.0.2.jar;.&quot; lua -l hello </pre> <p> The output <em>hello.class</em> 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). <p> Lua scripts can also be run directly in this mode without precompiling using the <em>lua</em> command with the <b><em>-b</em></b> option and providing the <em>bcel</em> library in the class path: <pre> java -cp &quot;luaj-jse-3.0.2.jar;lib/bcel-5.2.jar&quot; lua -b examples/lua/hello.lua </pre> <h2>Run a script in a Java Application</h2> <p> A simple hello, world example in luaj is: <pre> import org.luaj.vm2.*; import org.luaj.vm2.lib.jse.*; Globals globals = JsePlatform.standardGlobals(); LuaValue chunk = globals.load("print 'hello, world'"); chunk.call(); </pre>

Loading from a file is done via Globals.loadFile():

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

Chunks can also be loaded from a <code>Reader</code> as text source

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

or an InputStream to be loaded as text source "t", or binary lua file "b":

<pre> chunk = globals.load(new FileInputSStream("examples/lua/hello.lua"), "main.lua", "bt")); </pre> <p> A simple example may be found in <pre> <a href="examples/jse/SampleJseMain.java">examples/jse/SampleJseMain.java</a> </pre> <p> You must include the library <b>luaj-jse-3.0.2.jar</b> in your class path. <h2>Run a script in a MIDlet</h2> <p> For MIDlets the <em>JmePlatform</em> is used instead: <pre> import org.luaj.vm2.*; import org.luaj.vm2.lib.jme.*; Globals globals = JmePlatform.standardGlobals(); LuaValue chunk = globals.loadfile("examples/lua/hello.lua"); chunk.call(); </pre> <p> The file must be a resource within within the midlet jar for the loader 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> <a href="examples/jme/SampleMIDlet.java">examples/jme/SampleMIDlet.java</a> </pre> <p> You must include the library <b>luaj-jme-3.0.2.jar</b> in your midlet jar. <p> An ant script to build and run the midlet is in <pre> <a href="build-midlet.xml">build-midlet.xml</a> </pre> <p> You must install the wireless toolkit and define <em>WTK_HOME</em> for this script to work. <h2>Run a script using JSR-223 Dynamic Scripting</h2> <p> The standard use of JSR-223 scripting engines may be used: <pre> 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") ); </pre>

You can also look up the engine by language "lua" or mimetypes "text/lua" or "application/lua".

<p> All standard aspects of script engines including compiled statements are supported. <p> You must include the library <b>luaj-jse-3.0.2.jar</b> in your class path. <p> A working example may be found in <pre> <a href="examples/jse/ScriptEngineSample.java">examples/jse/ScriptEngineSample.java</a> </pre>

To compile and run it using Java 1.6 or higher:

<pre> javac -cp luaj-jse-3.0.2.jar examples/jse/ScriptEngineSample.java java -cp &quot;luaj-jse-3.0.2.jar;examples/jse&quot; ScriptEngineSample </pre> <h2>Excluding the lua bytecode compiler</h2>

By default, the compiler is included whenever <em>standardGlobals()</em> or <em>debugGlobals()</em> are called.
Without a compiler, files can still be executed, but they must