In typical usage, a Globals object must be created to hold global state, + * and it can be used to compile and load lua files into executable LuaValue + * instances. + * + * @see Globals + * @see LuaValue + */ public class SampleJseMain { public static void main(String[] args) throws Exception { @@ -12,7 +20,7 @@ public class SampleJseMain { // create an environment to run in Globals globals = JsePlatform.standardGlobals(); - // Use the convenience function on the globals to load a chunk. + // Use the convenience function on Globals to load a chunk. LuaValue chunk = globals.loadfile(script); // Use any of the "call()" or "invoke()" functions directly on the chunk. diff --git a/examples/jse/SampleMultiThreaded.java b/examples/jse/SampleMultiThreaded.java index 51fa6c9e..a0d5415e 100644 --- a/examples/jse/SampleMultiThreaded.java +++ b/examples/jse/SampleMultiThreaded.java @@ -5,11 +5,12 @@ import org.luaj.vm2.lib.jse.JsePlatform; /** Simple toy program illustrating how to run Luaj in multiple threads. * - * By creating separate Globals in each thread, scripts can be run in each thread. + *
By creating separate Globals in each thread, scripts can be run in each thread. * - * However note the following: - * - type-related metatables such as LuaNumber.s_metatable are shared by all threads, so are not thread-safe. - * - creating additional threads within a Java element called by lua could result in shared access to globals. + *
However note the following: + *
In this case, Globals are only indirectly constructed as a side effect + * of using the scripting interface. + * + *
All features should be supported including compiled scripts. + * + *
Configuration is via system properties: + *
These flag values can be set on the command line or via code. + */ public class ScriptEngineSample { public static void main(String [] args) { - // Set the property 'luaj.debug' before getting the engine to get + // Set the property 'org.luaj.debug' before getting the engine to get // the debug libraries, which will be slower, but may provide stack traces - // when luaJC is not used. - // System.setProperty("luaj.debug", "true"); + // when luaJC is not used. + // This can also be set on the command line using -Dorg.luaj.debug=true + // System.setProperty("org.luaj.debug", "true"); + // Set the property 'org.luaj.luajc' before getting the engine to enable + // the lua-to-java bytecode compiler, which requires the bcel library + // to be on the class path. + // This can also be set on the command line using -Dorg.luaj.luajc=true + // org.luaj.vm2.luajc.LuaJC.install(); + ScriptEngineManager sem = new ScriptEngineManager(); ScriptEngine e = sem.getEngineByName("luaj"); ScriptEngineFactory f = e.getFactory(); - // uncomment to enable the lua-to-java bytecode compiler - // (requires bcel library in class path) - // org.luaj.vm2.luajc.LuaJC.install(); - System.out.println( "Engine name: " +f.getEngineName() ); System.out.println( "Engine Version: " +f.getEngineVersion() ); System.out.println( "LanguageName: " +f.getLanguageName() ); diff --git a/src/core/org/luaj/vm2/Globals.java b/src/core/org/luaj/vm2/Globals.java index a5578d4c..9ce03571 100644 --- a/src/core/org/luaj/vm2/Globals.java +++ b/src/core/org/luaj/vm2/Globals.java @@ -35,10 +35,10 @@ import org.luaj.vm2.lib.ResourceFinder; * Global environment used by luaj. *
* Contains the global variables referenced by lua libraries such as stdin and stdout, - * the resrouce finder which is used tolook up files in a platform independent way, + * the resource finder which is used to look up files in a platform independent way, * the installed lua compiler, the math library in use, debugging calls stack, and so on. *
- * In a multithreded server environment, each server thread should create one Globals instance, + * In a multi-threaded server environment, each server thread should create one Globals instance, * which will be logically distance and not interfere with each other, but share certain * static immutable resources such as class data and string data. *
@@ -46,12 +46,12 @@ import org.luaj.vm2.lib.ResourceFinder; * {@link JsePlatform.standardGlobasl()} or {@link JmePlatform.standardGlobals()}, * and then used to load lua scripts for execution as in the following example. *
{@code
- * Globals _G = JsePlatform.standardGlobals();
- * _G.compiler.load( new ByteArrayInputStream("print 'hello'".getBytes()), "main.lua", _G ).call();
+ * Globals globals = JsePlatform.standardGlobals();
+ * globals.compiler.load( new ByteArrayInputStream("print 'hello'".getBytes()), "main.lua", _G ).call();
* }
* @see LuaCompiler
- * @see JsePlatform
- * @see JmePlatform
+ * @see org.luaj.vm2.lib.jse.JsePlatform
+ * @see org.luaj.vm2.lib.jme.JmePlatform
* @see LuaValue
*
*/
@@ -107,13 +107,16 @@ public class Globals extends LuaTable {
return this;
}
- /** The installed loader. */
+ /** The installed loader.
+ * @see Loader */
public Loader loader;
- /** The installed compiler. */
+ /** The installed compiler.
+ * @see Compiler */
public Compiler compiler;
- /** The installed undumper. */
+ /** The installed undumper.
+ * @see Undumper */
public Undumper undumper;
/** Convenience function for loading a file that is either binary lua or lua source.
diff --git a/src/core/org/luaj/vm2/lib/CoroutineLib.java b/src/core/org/luaj/vm2/lib/CoroutineLib.java
index b8c38d4f..8c8bb298 100644
--- a/src/core/org/luaj/vm2/lib/CoroutineLib.java
+++ b/src/core/org/luaj/vm2/lib/CoroutineLib.java
@@ -22,7 +22,6 @@
package org.luaj.vm2.lib;
import org.luaj.vm2.Globals;
-import org.luaj.vm2.LuaError;
import org.luaj.vm2.LuaTable;
import org.luaj.vm2.LuaThread;
import org.luaj.vm2.LuaValue;
diff --git a/src/jme/org/luaj/vm2/lib/jme/JmeIoLib.java b/src/jme/org/luaj/vm2/lib/jme/JmeIoLib.java
index 676a110d..3d9de48f 100644
--- a/src/jme/org/luaj/vm2/lib/jme/JmeIoLib.java
+++ b/src/jme/org/luaj/vm2/lib/jme/JmeIoLib.java
@@ -30,7 +30,6 @@ import javax.microedition.io.StreamConnection;
import org.luaj.vm2.LuaString;
import org.luaj.vm2.LuaValue;
-import org.luaj.vm2.lib.BaseLib;
import org.luaj.vm2.lib.IoLib;
import org.luaj.vm2.lib.LibFunction;
@@ -43,27 +42,30 @@ import org.luaj.vm2.lib.LibFunction;
* * Typically, this library is included as part of a call to * {@link JmePlatform#standardGlobals()} - *
- * To instantiate and use it directly, - * link it into your globals table via {@link LuaValue#load(LuaValue)} using code such as: *
{@code
- * LuaTable _G = new LuaTable();
- * LuaThread.setGlobals(_G);
- * _G.load(new BaseLib());
- * _G.load(new PackageLib());
- * _G.load(new JmeIoLib());
- * _G.get("io").get("write").call(LuaValue.valueOf("hello, world\n"));
+ * Globals globals = JmePlatform.standardGlobals();
+ * globals.get("io").get("write").call(LuaValue.valueOf("hello, world\n"));
* }
- * Doing so will ensure the library is properly initialized
- * and loaded into the globals table.
+ * + * For special cases where the smallest possible footprint is desired, + * a minimal set of libraries could be loaded + * directly via {@link Glboals#load(LuaValue)} using code such as: + *
{@code
+ * Globals globals = new Globals();
+ * globals.load(new JmeBaseLib());
+ * globals.load(new PackageLib());
+ * globals.load(new JmeIoLib());
+ * globals.get("io").get("write").call(LuaValue.valueOf("hello, world\n"));
+ * }
+ * However, other libraries such as MathLib are not loaded in this case. *
* This has been implemented to match as closely as possible the behavior in the corresponding library in C. * @see LibFunction - * @see JsePlatform + * @see org.luaj.vm2.lib.jse.JsePlatform * @see JmePlatform * @see IoLib * @see JseIoLib - * @see http://www.lua.org/manual/5.1/manual.html#5.6 + * @see Lua 5.2 I/O Lib Reference */ public class JmeIoLib extends IoLib { diff --git a/src/jme/org/luaj/vm2/lib/jme/JmePlatform.java b/src/jme/org/luaj/vm2/lib/jme/JmePlatform.java index fedc6b09..012671a3 100644 --- a/src/jme/org/luaj/vm2/lib/jme/JmePlatform.java +++ b/src/jme/org/luaj/vm2/lib/jme/JmePlatform.java @@ -53,18 +53,18 @@ import org.luaj.vm2.lib.TableLib; *
* A simple example of initializing globals and using them from Java is: *
{@code
- * Globals _G = JmePlatform.standardGlobals();
- * _G.get("print").call(LuaValue.valueOf("hello, world"));
+ * Globals global = JmePlatform.standardGlobals();
+ * global.get("print").call(LuaValue.valueOf("hello, world"));
* }
* * Once globals are created, a simple way to load and run a script is: *
{@code
- * LoadState.load( getClass().getResourceAsStream("main.lua"), "main.lua", _G ).call();
+ * LoadState.load( getClass().getResourceAsStream("main.lua"), "main.lua", globals ).call();
* }
* * although {@code require} could also be used: *
{@code
- * _G.get("require").call(LuaValue.valueOf("main"));
+ * globals.get("require").call(LuaValue.valueOf("main"));
* }
* For this to succeed, the file "main.lua" must be a resource in the class path.
* See {@link BaseLib} for details on finding scripts using {@link ResourceFinder}.
@@ -103,19 +103,19 @@ public class JmePlatform {
* @see JmePlatform
*/
public static Globals standardGlobals() {
- Globals _G = new Globals();
- _G.load(new BaseLib());
- _G.load(new PackageLib());
- _G.load(new Bit32Lib());
- _G.load(new OsLib());
- _G.load(new MathLib());
- _G.load(new TableLib());
- _G.load(new StringLib());
- _G.load(new CoroutineLib());
- _G.load(new JmeIoLib());
- LoadState.install(_G);
- LuaC.install(_G);
- return _G;
+ Globals globals = new Globals();
+ globals.load(new BaseLib());
+ globals.load(new PackageLib());
+ globals.load(new Bit32Lib());
+ globals.load(new OsLib());
+ globals.load(new MathLib());
+ globals.load(new TableLib());
+ globals.load(new StringLib());
+ globals.load(new CoroutineLib());
+ globals.load(new JmeIoLib());
+ LoadState.install(globals);
+ LuaC.install(globals);
+ return globals;
}
/** Create standard globals including the {@link debug} library.
@@ -127,8 +127,8 @@ public class JmePlatform {
* @see DebugLib
*/
public static Globals debugGlobals() {
- Globals _G = standardGlobals();
- _G.load(new DebugLib());
- return _G;
+ Globals globals = standardGlobals();
+ globals.load(new DebugLib());
+ return globals;
}
}
diff --git a/src/jse/org/luaj/vm2/lib/jse/JseBaseLib.java b/src/jse/org/luaj/vm2/lib/jse/JseBaseLib.java
index 0ff68d9a..d67150bb 100644
--- a/src/jse/org/luaj/vm2/lib/jse/JseBaseLib.java
+++ b/src/jse/org/luaj/vm2/lib/jse/JseBaseLib.java
@@ -43,26 +43,30 @@ import org.luaj.vm2.lib.ResourceFinder;
* * Typically, this library is included as part of a call to * {@link JsePlatform#standardGlobals()} - *
- * To instantiate and use it directly, - * link it into your globals table via {@link LuaValue#load(LuaValue)} using code such as: *
{@code
- * LuaTable _G = new LuaTable();
- * LuaThread.setGlobals(_G);
- * _G.load(new JseBaseLib());
- * _G.get("print").call(LuaValue.valueOf("hello, world"));
+ * Globals globals = JsePlatform.standardGlobals();
+ * globals.get("print").call(LuaValue.valueOf("hello, world"));
* }
- * Doing so will ensure the library is properly initialized
- * and loaded into the globals table.
+ * + * For special cases where the smallest possible footprint is desired, + * a minimal set of libraries could be loaded + * directly via {@link Globals#load(LuaValue)} using code such as: + *
{@code
+ * Globals globals = new Globals();
+ * globals.load(new JseBaseLib());
+ * globals.get("print").call(LuaValue.valueOf("hello, world"));
+ * }
+ * However, other libraries such as PackageLib are not loaded in this case. *
* This is a direct port of the corresponding library in C. + * @see Globals * @see BaseLib * @see ResourceFinder - * @see #FINDER + * @see {@link Globals.FINDER} * @see LibFunction * @see JsePlatform - * @see JmePlatform - * @see http://www.lua.org/manual/5.1/manual.html#5.1 + * @see org.luaj.vm2.lib.jme.JmePlatform + * @see Lua 5.2 Base Lib Reference */ public class JseBaseLib extends org.luaj.vm2.lib.BaseLib { diff --git a/src/jse/org/luaj/vm2/lib/jse/JseIoLib.java b/src/jse/org/luaj/vm2/lib/jse/JseIoLib.java index 54b3fcfd..99c19abe 100644 --- a/src/jse/org/luaj/vm2/lib/jse/JseIoLib.java +++ b/src/jse/org/luaj/vm2/lib/jse/JseIoLib.java @@ -21,7 +21,6 @@ ******************************************************************************/ package org.luaj.vm2.lib.jse; - import java.io.BufferedInputStream; import java.io.EOFException; import java.io.IOException; @@ -33,7 +32,6 @@ import java.io.RandomAccessFile; import org.luaj.vm2.LuaError; import org.luaj.vm2.LuaString; import org.luaj.vm2.LuaValue; -import org.luaj.vm2.lib.BaseLib; import org.luaj.vm2.lib.IoLib; import org.luaj.vm2.lib.LibFunction; @@ -45,27 +43,30 @@ import org.luaj.vm2.lib.LibFunction; *
* Typically, this library is included as part of a call to * {@link JsePlatform#standardGlobals()} - *
- * To instantiate and use it directly, - * link it into your globals table via {@link LuaValue#load(LuaValue)} using code such as: *
{@code
- * LuaTable _G = new LuaTable();
- * LuaThread.setGlobals(_G);
- * _G.load(new JseBaseLib());
- * _G.load(new PackageLib());
- * _G.load(new JseIoLib());
- * _G.get("io").get("write").call(LuaValue.valueOf("hello, world\n"));
+ * Globals globals = JsePlatform.standardGlobals();
+ * globals.get("io").get("write").call(LuaValue.valueOf("hello, world\n"));
* }
- * Doing so will ensure the library is properly initialized
- * and loaded into the globals table.
+ * + * For special cases where the smallest possible footprint is desired, + * a minimal set of libraries could be loaded + * directly via {@link Glboals#load(LuaValue)} using code such as: + *
{@code
+ * Globals globals = new Globals();
+ * globals.load(new JseBaseLib());
+ * globals.load(new PackageLib());
+ * globals.load(new JseIoLib());
+ * globals.get("io").get("write").call(LuaValue.valueOf("hello, world\n"));
+ * }
+ * However, other libraries such as MathLib are not loaded in this case. *
* This has been implemented to match as closely as possible the behavior in the corresponding library in C. * @see LibFunction * @see JsePlatform - * @see JmePlatform + * @see org.luaj.vm2.lib.jme.JmePlatform * @see IoLib * @see JmeIoLib - * @see http://www.lua.org/manual/5.1/manual.html#5.7 + * @see Lua 5.2 I/O Lib Reference */ public class JseIoLib extends IoLib { diff --git a/src/jse/org/luaj/vm2/lib/jse/JseMathLib.java b/src/jse/org/luaj/vm2/lib/jse/JseMathLib.java index deadb647..fce8c4c7 100644 --- a/src/jse/org/luaj/vm2/lib/jse/JseMathLib.java +++ b/src/jse/org/luaj/vm2/lib/jse/JseMathLib.java @@ -32,27 +32,30 @@ import org.luaj.vm2.lib.LibFunction; * See {@link org.luaj.lib.MathLib} for the exception list. *
* Typically, this library is included as part of a call to - * {@link JsePlatform#standardGlobals()} - *
- * To instantiate and use it directly, - * link it into your globals table via {@link LuaValue#load(LuaValue)} using code such as: + * {@link JsePlatform#standardGlobals()} *
{@code
- * LuaTable _G = new LuaTable();
- * LuaThread.setGlobals(_G);
- * _G.load(new JseBaseLib());
- * _G.load(new PackageLib());
- * _G.load(new JseMathLib());
+ * Globals globals = JsePlatform.standardGlobals();
* System.out.println( _G.get("math").get("sqrt").call( LuaValue.valueOf(2) ) );
* }
- * Doing so will ensure the library is properly initialized
- * and loaded into the globals table.
+ * + * For special cases where the smallest possible footprint is desired, + * a minimal set of libraries could be loaded + * directly via {@link Glboals#load(LuaValue)} using code such as: + *
{@code
+ * Globals globals = new Globals();
+ * globals.load(new JseBaseLib());
+ * globals.load(new PackageLib());
+ * globals.load(new JseMathLib());
+ * System.out.println( _G.get("math").get("sqrt").call( LuaValue.valueOf(2) ) );
+ * }
+ * However, other libraries such as CoroutineLib are not loaded in this case. *
* This has been implemented to match as closely as possible the behavior in the corresponding library in C. * @see LibFunction * @see JsePlatform - * @see JmePlatform + * @see org.luaj.vm2.lib.jme.JmePlatform * @see JseMathLib - * @see http://www.lua.org/manual/5.1/manual.html#5.6 + * @see Lua 5.2 Math Lib Reference */ public class JseMathLib extends org.luaj.vm2.lib.MathLib { diff --git a/src/jse/org/luaj/vm2/lib/jse/JseOsLib.java b/src/jse/org/luaj/vm2/lib/jse/JseOsLib.java index 082d7c20..09ea94fb 100644 --- a/src/jse/org/luaj/vm2/lib/jse/JseOsLib.java +++ b/src/jse/org/luaj/vm2/lib/jse/JseOsLib.java @@ -20,6 +20,7 @@ * THE SOFTWARE. ******************************************************************************/ package org.luaj.vm2.lib.jse; + import java.io.File; import java.io.IOException; @@ -43,27 +44,30 @@ import org.luaj.vm2.lib.LibFunction; * os-specific features, the behavior of these functions varies considerably * from their counterparts in the C platform. *
- * Typically, this library is included as part of a call to either + * Typically, this library is included as part of a call to * {@link JsePlatform#standardGlobals()} - *
- * To instantiate and use it directly, - * link it into your globals table via {@link LuaValue#load(LuaValue)} using code such as: *
{@code
- * LuaTable _G = new LuaTable();
- * LuaThread.setGlobals(_G);
- * _G.load(new JseBaseLib());
- * _G.load(new PackageLib());
- * _G.load(new JseOsLib());
+ * Globals globals = JsePlatform.standardGlobals();
* System.out.println( _G.get("os").get("time").call() );
* }
- * Doing so will ensure the library is properly initialized
- * and loaded into the globals table.
+ * + * For special cases where the smallest possible footprint is desired, + * a minimal set of libraries could be loaded + * directly via {@link Glboals#load(LuaValue)} using code such as: + *
{@code
+ * Globals globals = new Globals();
+ * globals.load(new JseBaseLib());
+ * globals.load(new PackageLib());
+ * globals.load(new JseOsLib());
+ * System.out.println( _G.get("os").get("time").call() );
+ * }
+ * However, other libraries such as MathLib are not loaded in this case. *
* @see LibFunction * @see OsLib * @see JsePlatform - * @see JmePlatform - * @see http://www.lua.org/manual/5.1/manual.html#5.8 + * @see org.luaj.vm2.lib.jme.JmePlatform + * @see Lua 5.2 OS Lib Reference */ public class JseOsLib extends org.luaj.vm2.lib.OsLib { diff --git a/src/jse/org/luaj/vm2/lib/jse/JsePlatform.java b/src/jse/org/luaj/vm2/lib/jse/JsePlatform.java index 08b36a1b..c987904e 100644 --- a/src/jse/org/luaj/vm2/lib/jse/JsePlatform.java +++ b/src/jse/org/luaj/vm2/lib/jse/JsePlatform.java @@ -42,18 +42,18 @@ import org.luaj.vm2.lib.TableLib; *
* A simple example of initializing globals and using them from Java is: *
{@code
- * Globals _G = JsePlatform.standardGlobals();
- * _G.get("print").call(LuaValue.valueOf("hello, world"));
+ * Globals globals = JsePlatform.standardGlobals();
+ * globals.get("print").call(LuaValue.valueOf("hello, world"));
* }
* * Once globals are created, a simple way to load and run a script is: *
{@code
- * _G.load( new FileInputStream("main.lua"), "main.lua" ).call();
+ * globals.load( new FileInputStream("main.lua"), "main.lua" ).call();
* }
* * although {@code require} could also be used: *
{@code
- * _G.get("require").call(LuaValue.valueOf("main"));
+ * globals.get("require").call(LuaValue.valueOf("main"));
* }
* For this to succeed, the file "main.lua" must be in the current directory or a resource.
* See {@link JseBaseLib} for details on finding scripts using {@link ResourceFinder}.
@@ -91,20 +91,20 @@ public class JsePlatform {
* @see JmePlatform
*/
public static Globals standardGlobals() {
- Globals _G = new Globals();
- _G.load(new JseBaseLib());
- _G.load(new PackageLib());
- _G.load(new Bit32Lib());
- _G.load(new TableLib());
- _G.load(new StringLib());
- _G.load(new CoroutineLib());
- _G.load(new JseMathLib());
- _G.load(new JseIoLib());
- _G.load(new JseOsLib());
- _G.load(new LuajavaLib());
- LoadState.install(_G);
- LuaC.install(_G);
- return _G;
+ Globals globals = new Globals();
+ globals.load(new JseBaseLib());
+ globals.load(new PackageLib());
+ globals.load(new Bit32Lib());
+ globals.load(new TableLib());
+ globals.load(new StringLib());
+ globals.load(new CoroutineLib());
+ globals.load(new JseMathLib());
+ globals.load(new JseIoLib());
+ globals.load(new JseOsLib());
+ globals.load(new LuajavaLib());
+ LoadState.install(globals);
+ LuaC.install(globals);
+ return globals;
}
/** Create standard globals including the {@link debug} library.
@@ -116,9 +116,9 @@ public class JsePlatform {
* @see DebugLib
*/
public static Globals debugGlobals() {
- Globals _G = standardGlobals();
- _G.load(new DebugLib());
- return _G;
+ Globals globals = standardGlobals();
+ globals.load(new DebugLib());
+ return globals;
}
diff --git a/test/junit/org/luaj/vm2/script/ScriptEngineTests.java b/test/junit/org/luaj/vm2/script/ScriptEngineTests.java
index 031896c0..3ec80ae2 100644
--- a/test/junit/org/luaj/vm2/script/ScriptEngineTests.java
+++ b/test/junit/org/luaj/vm2/script/ScriptEngineTests.java
@@ -95,11 +95,13 @@ public class ScriptEngineTests extends TestSuite {
}
public static class LuaJCBindingsTest extends EngineTestCase {
+ static {
+ System.setProperty("org.luaj.luajc", "true");
+ }
protected Bindings createBindings() {
return new SimpleBindings();
}
public void setUp() {
- System.setProperty("org.luaj.luajc", "true");
super.setUp();
}
public void testCompiledFunctionIsNotClosure() throws ScriptException {