- -Copyright © 2009-2014 Luaj.org. -Freely available under the terms of the -Luaj license. - + + 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 + introduction + · + examples + · + concepts + · + libraries + · + luaj api + · + parser + · + building + · + downloads + · + release notes - +
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
+
|
+ ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
-From the main distribution directory line type: + 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: + You should see the following output:
hello, world@@ -202,7 +213,8 @@ To see how luaj can be used to acccess most Java API's including swing, try:
-Links to sources:
+ Links to sources: +examples/lua/hello.lua examples/lua/swingapp.lua@@ -210,7 +222,7 @@ Links to sources:Compile lua source to lua bytecode
-From the main distribution directory line type: + From the main distribution directory line type:
java -cp lib/luaj-jse-3.0.1.jar luac examples/lua/hello.lua @@ -218,13 +230,14 @@ From the main distribution directory line type:-The compiled output "luac.out" is lua bytecode and should run and produce the same result. + 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: + 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 @@ -233,12 +246,14 @@ Luaj can compile lua sources or binaries directly to java bytecode if the bcel l-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). + 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: + 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@@ -247,7 +262,7 @@ Lua scripts can also be run directly in this mode without precompiling using theRun a script in a Java Application
-A simple hello, world example in luaj is: + A simple hello, world example in luaj is:
import org.luaj.vm2.*; @@ -256,7 +271,7 @@ A simple hello, world example in luaj is: Globals globals = JsePlatform.standardGlobals(); LuaValue chunk = globals.load("print 'hello, world'"); chunk.call(); - +Loading from a file is done via Globals.loadFile(): @@ -278,18 +293,18 @@ or an InputStream to be loaded as text source "t", or binary lua file "b":-A simple example may be found in + 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. + 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: + For MIDlets the JmePlatform is used instead:
import org.luaj.vm2.*; @@ -301,31 +316,31 @@ For MIDlets the JmePlatform is used instead:-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. + 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 + 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. + 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 + 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. + 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: + The standard use of JSR-223 scripting engines may be used:
ScriptEngineManager mgr = new ScriptEngineManager(); @@ -338,13 +353,13 @@ The standard use of JSR-223 scripting engines may be used: You can also look up the engine by language "lua" or mimetypes "text/lua" or "application/lua".-All standard aspects of script engines including compiled statements are supported. + 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. + You must include the library lib/luaj-jse-3.0.1.jar in your class path.
-A working example may be found in + A working example may be found in
examples/jse/ScriptEngineSample.java@@ -358,15 +373,15 @@ To compile and run it using Java 1.6 or higher:Excluding the lua bytecode compiler
-By default, the compiler is included whenever standardGlobals() or debugGlobals() are called. +By default, the compiler is included whenever standardGlobals() or debugGlobals() are called. 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. +The "luac" utility is provided in the jse jar for this purpose, or a standard lua compiler can be used.-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: + 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);@@ -375,75 +390,75 @@ that are needed and omitting the line: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: + 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. + 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. + The requires bcel to be on the class path, and the ClassLoader of JSE or CDC.
3 - Concepts
Globals
-The old notion of platform has been replaced with creation of globals. -The Globals -class holds global state needed for executing closures as well as providing +The old notion of platform has been replaced with creation of globals. +The Globals +class holds global state needed for executing closures as well as providing convenience functions for compiling and loading scripts.Platform
-To simplify construction of Globals, and encapsulate differences needed to support -the diverse family of Java runtimes, luaj uses a Platform notion. -Typically, a platform is used to construct a Globals, which is then provided as a global +To simplify construction of Globals, and encapsulate differences needed to support +the diverse family of Java runtimes, luaj uses a Platform notion. +Typically, a platform is used to construct a Globals, which is then provided as a global environment for client scripts.JsePlatform
-The JsePlatform -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 JsePlatform +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 Java SE.Android
-Android applications should use the JsePlatform, and can include the Luajava library -to simplify access to underlying Android APIs. +Android applications should use the JsePlatform, and can include the Luajava library +to simplify access to underlying Android APIs. A specialized Globals.finder should be provided to find scripts and data for loading. See examples/android/src/android/LuajView for an example that loads from the "res" Android project directory. -The ant build script is examples/android/build.xml. +The ant build script is examples/android/build.xml.Applet
-Applets in browsers should use the JsePlatform. The permissions model in applets is -highly restrictive, so a specialization of the Luajava library must be used that -uses default class loading. This is illustrated in the sample Applet -examples/jse/SampleApplet.java, +Applets in browsers should use the JsePlatform. The permissions model in applets is +highly restrictive, so a specialization of the Luajava library must be used that +uses default class loading. This is illustrated in the sample Applet +examples/jse/SampleApplet.java, which can be built using build-applet.xml.JmePlatform
-The JmePlatform +The JmePlatform 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 Java ME. -All libraries are included except luajava, and the os, io, and math libraries are +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.MIDlet
-MIDlets require the JmePlatform. +MIDlets require the JmePlatform. The JME platform has several limitations which carry over to luaj. -In particular Globals.finder is overridden to load as resources, so scripts should be -colocated with class files in the MIDlet jar file. Luajava cannot be used. -Camples code is in -examples/jme/SampleMIDlet.java, +In particular Globals.finder is overridden to load as resources, so scripts should be +colocated with class files in the MIDlet jar file. Luajava cannot be used. +Camples code is in +examples/jme/SampleMIDlet.java, which can be built using build-midlet.xml. @@ -451,50 +466,52 @@ which can be built using build-midlet.xml. Luaj 3.0 can be run in multiple threads, with the following restrictions:
-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. + 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.
-Considerations include + Considerations include
-The following libraries are loaded by both JsePlatform.standardGlobals() and JmePlatform.standardGlobals(): + The following libraries are loaded by both JsePlatform.standardGlobals() and JmePlatform.standardGlobals():
base bit32 coroutine @@ -507,12 +524,13 @@ The following libraries are loaded by both JsePlatform.standardGlobals()-The JsePlatform.standardGlobals() globals also include: -
luajava + The JsePlatform.standardGlobals() globals also include: +- + See the Varargs API for a complete list. - +luajava-The JsePlatform.debugGlobals() and JsePlatform.debugGlobals() functions produce globals that include: + The JsePlatform.debugGlobals() and JsePlatform.debugGlobals() functions produce globals that + include:
debug@@ -520,12 +538,12 @@ The JsePlatform.debugGlobals() and JsePlatform.debugGlobals() The implementation of the io library differs by platform owing to platform limitations.-The JmePlatform.standardGlobals() instantiated the io library io in + The JmePlatform.standardGlobals() instantiated the io library io in
src/jme/org/luaj/vm2/lib/jme/JmeIoLib.java-The JsePlatform.standardGlobals() includes support for random access and is in +The JsePlatform.standardGlobals() includes support for random access and is insrc/jse/org/luaj/vm2/lib/jse/JseIoLib.java@@ -534,38 +552,38 @@ The JsePlatform.standardGlobals() includes support for random access an The implementation of the os library also differs per platform.-The basic os library implementation us used by JmePlatform and is in: + The basic os library implementation us used by JmePlatform and is in:
src/core/org/luaj/lib/OsLib.java-A richer version for use by JsePlatform is : +A richer version for use by JsePlatform is :src/jse/org/luaj/vm2/lib/jse/JseOsLib.java-Time is a represented as number of seconds since the epoch, +Time is a represented as number of seconds since the epoch, and locales are not implemented.Coroutine Library
-The coroutine library is implemented using one JavaThread per coroutine. -This allows coroutine.yield() can be called from anywhere, -as with the yield-from-anywhere patch in C-based lua. +The coroutine library is implemented using one JavaThread per coroutine. +This allows coroutine.yield() can be called from anywhere, +as with the yield-from-anywhere patch in C-based lua.-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. + 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
-The debug library is not included by default by +The debug library is not included by default by JmePlatform.standardGlobals() or JsePlatform.standardGlobsls() . -The functions JmePlatform.debugGlobals() and JsePlatform.debugGlobsls() -create globals that contain the debug library in addition to the other standard libraries. +The functions JmePlatform.debugGlobals() and JsePlatform.debugGlobsls() +create globals that contain the debug library in addition to the other standard libraries. To install dynamically from lua use java-class-based require::@@ -576,11 +594,12 @@ The lua command line utility includes the debug library by def-You can also build a local version from sources using +You can also build a local version from sources usingThe Luajava Library
-The JsePlatform.standardGlobals() includes the luajava library, which simplifies binding to Java classes and methods. +The JsePlatform.standardGlobals() includes the luajava library, which simplifies binding to Java +classes and methods. It is patterned after the original luajava project.-The following lua script will open a swing frame on Java SE: + 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" ); @@ -590,17 +609,19 @@ The following lua script will open a swing frame on Java SE:-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: + 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 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. + The lua connand line tool includes luajava.
5 - LuaJ API
@@ -610,21 +631,21 @@ The javadoc for the main classes in the LuaJ API are on line at http://luaj.org/luaj/3.0/apiant docLuaValue and Varargs
-All lua value manipulation is now organized around +All lua value manipulation is now organized around LuaValue -which exposes the majority of interfaces used for lua computation. +which exposes the majority of interfaces used for lua computation.org.luaj.vm2.LuaValueCommon Functions
-LuaValue exposes functions for each of the operations in LuaJ. +LuaValue exposes functions for each of the operations in LuaJ. Some commonly used functions and constants include:call(); // invoke the function with no arguments @@ -639,14 +660,14 @@ Some commonly used functions and constants include: tojstring(); // return value as a Java String isnil(); // is the value nil NIL; // the value nil - NONE; // a Varargs instance with no values + NONE; // a Varargs instance with no valuesVarargs
-The interface Varargs provides an abstraction for -both a variable argument list and multiple return values. -For convenience, LuaValue implements Varargs so a single value can be supplied anywhere -variable arguments are expected. +The interface Varargs provides an abstraction for +both a variable argument list and multiple return values. +For convenience, LuaValue implements Varargs so a single value can be supplied anywhere +variable arguments are expected.org.luaj.vm2.Varargs@@ -661,13 +682,13 @@ variable arguments are expected. 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 longLibFunction
The simplest way to implement a function is to choose a base class based on the number of arguments to the function. -LuaJ provides 5 base classes for this purpose, depending if the function has 0, 1, 2, 3 or variable arguments, -and if it provide multiple return values. +LuaJ provides 5 base classes for this purpose, depending if the function has 0, 1, 2, 3 or variable arguments, +and if it provide multiple return values.org.luaj.vm2.lib.ZeroArgFunction org.luaj.vm2.lib.OneArgFunction @@ -676,11 +697,11 @@ and if it provide multiple return values. org.luaj.vm2.lib.VarArgFunction-Each of these functions has an abstract method that must be implemented, +Each 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: + An example of a function with no arguments but a useful return value might be:
pubic class hostname extends ZeroArgFunction { public LuaValue call() { @@ -689,42 +710,42 @@ An example of a function with no arguments but a useful return value might be: }-The value env is the environment of the function, and is normally supplied -by the instantiating object whenever default loading is used. +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: -
+ 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. +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.Libraries of Java Functions
-When require() is called, it will first attempt to load the module as a Java class that implements LuaFunction. +When require() is called, it will first attempt to load the module as a Java class that implements LuaFunction. To succeed, the following requirements must be met:
-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. + 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 + 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.*;
@@ -746,7 +767,7 @@ public class hyperbolic extends TwoArgFunction {
return LuaValue.valueOf(Math.sinh(x.checkdouble()));
}
}
-
+
static class cosh extends OneArgFunction {
public LuaValue call(LuaValue x) {
return LuaValue.valueOf(Math.cosh(x.checkdouble()));
@@ -755,11 +776,11 @@ public class hyperbolic extends TwoArgFunction {
}
-In this case the call to require invokes the library itself to initialize it. The library implementation
+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 + The lua script used to load and test it is in examples/lua/hyperbolicapp.lua
require 'hyperbolic' @@ -772,37 +793,39 @@ The lua script used to load and test it is in org.luaj.vm2.LuaClosure -javadoc for details on using that class directly. + See the org.luaj.vm2.LuaClosure + javadoc for details on using that class directly.An example that prints locations of all function definitions in a file may be found in6 - Parser
Javacc Grammar
A Javacc grammar was developed to simplify the creation of Java-based parsers for the lua language. -The grammar is specified for javacc version 5.0 because that tool generates standalone -parsers that do not require a separate runtime. +The grammar is specified for javacc version 5.0 because that tool generates +standalone +parsers that do not require a separate runtime.-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 + 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
-The default lu compiler does a single-pass compile of lua source to lua bytecode, so no explicit parse tree is produced. +The default lu compiler does a single-pass compile of lua source to lua bytecode, so no explicit parse tree is produced.-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. + 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: + For example, to parse a file and print all variable names, use code like:
try { String file = "main.lua"; @@ -818,10 +841,10 @@ For example, to parse a file and print all variable names, use code like: } catch ( ParseException e ) { System.out.println("parse failed: " + e.getMessage() + "\n" + "Token Image: '" + e.currentToken.image + "'\n" - + "Location: " + e.currentToken.beginLine + ":" + e.currentToken.beginColumn + + "Location: " + e.currentToken.beginLine + ":" + e.currentToken.beginColumn + "-" + e.currentToken.endLine + "," + e.currentToken.endColumn); } -+
@@ -829,21 +852,23 @@ An example that prints locations of all function definitions in a file may be fo
-See the org.luaj.vm2.ast package javadoc for the API relating to the syntax tree that is produced. + 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: + 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>
while for JME projects, use the luaj-jme jar:
@@ -851,10 +876,10 @@ while for JME projects, use the luaj-jme jar:
<groupId>org.luaj</groupId>
<artifactId>luaj-jme</artifactId>
<version>3.0.1</version>
- </dependency>
+ </dependency>
-An example skelton maven pom file for a skeleton project is in
+An example skelton maven pom file for a skeleton project is in
examples/maven/pom.xml@@ -864,18 +889,18 @@ An example skelton maven pom file for a skeleton project is in An ant file is included in the root directory which builds the libraries by default.
-Other targets exist for creating distribution file an measuring code coverage of unit tests. + 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: + 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 + Unit test scripts can be found in these locations
test/lua/*.lua test/lua/errors/*.lua @@ -886,7 +911,7 @@ Unit test scripts can be found in these locationsCode coverage
-A build script for running unit tests and producing code coverage statistics is in + A build script for running unit tests and producing code coverage statistics is in
build-coverage.xml@@ -896,8 +921,8 @@ It relies on the cobertura code coverage library.8 - Downloads
Downloads and Project Pages
-Downloads for all version available on SourceForge or LuaForge. -Sources are hosted on SourceForge and available via sourceforge.net +Downloads for all version available on SourceForge or LuaForge. +Sources are hosted on SourceForge and available via sourceforge.net
SourceForge Luaj Project Page @@ -911,143 +936,216 @@ Files are no longer hosted at LuaForge.9 - Release Notes
Main Changes by Version
-
|
+