From de33943eafdbca17df86b5b70455a70d3c80f132 Mon Sep 17 00:00:00 2001 From: James Roseborough Date: Sun, 29 Dec 2013 22:49:23 +0000 Subject: [PATCH] Update javadoc comments related to library initialization and loading lua code. --- src/core/org/luaj/vm2/Globals.java | 79 ++++++++++++++++--- src/core/org/luaj/vm2/LoadState.java | 52 ++++++++---- src/core/org/luaj/vm2/LuaClosure.java | 37 +++++---- src/core/org/luaj/vm2/Print.java | 30 ++++--- src/core/org/luaj/vm2/Prototype.java | 53 ++++++++++++- src/core/org/luaj/vm2/compiler/DumpState.java | 36 ++++++++- src/core/org/luaj/vm2/compiler/LuaC.java | 29 +++++-- src/core/org/luaj/vm2/lib/BaseLib.java | 24 +++--- src/core/org/luaj/vm2/lib/Bit32Lib.java | 23 ++++++ src/core/org/luaj/vm2/lib/CoroutineLib.java | 15 ++-- src/core/org/luaj/vm2/lib/DebugLib.java | 15 ++-- src/core/org/luaj/vm2/lib/IoLib.java | 21 ++--- src/core/org/luaj/vm2/lib/MathLib.java | 21 +++-- src/core/org/luaj/vm2/lib/OsLib.java | 21 ++--- src/core/org/luaj/vm2/lib/PackageLib.java | 42 +++++++--- src/core/org/luaj/vm2/lib/StringLib.java | 20 ++--- src/core/org/luaj/vm2/lib/TableLib.java | 23 +++--- src/jme/org/luaj/vm2/lib/jme/JmeIoLib.java | 2 +- src/jse/lua.java | 22 +++--- .../org/luaj/vm2/lib/jse/CoerceJavaToLua.java | 2 - .../org/luaj/vm2/lib/jse/CoerceLuaToJava.java | 5 -- src/jse/org/luaj/vm2/lib/jse/JavaClass.java | 1 - src/jse/org/luaj/vm2/lib/jse/JseIoLib.java | 2 +- src/jse/org/luaj/vm2/lib/jse/JseMathLib.java | 6 +- src/jse/org/luaj/vm2/lib/jse/JseOsLib.java | 6 +- src/jse/org/luaj/vm2/lib/jse/LuajavaLib.java | 38 +++++---- src/jse/org/luaj/vm2/luajc/LuaJC.java | 27 ++++--- src/jse/org/luaj/vm2/luajc/ProtoInfo.java | 1 - test/java/org/luaj/luajc/TestLuaJ.java | 4 +- test/java/org/luaj/luajc/TestLuaJC.java | 14 ++-- test/junit/org/luaj/vm2/FragmentsTest.java | 10 +-- .../junit/org/luaj/vm2/LuaOperationsTest.java | 14 ++-- test/junit/org/luaj/vm2/ScriptDrivenTest.java | 8 +- .../luaj/vm2/compiler/AbstractUnitTests.java | 8 +- .../vm2/compiler/DumpLoadEndianIntTest.java | 10 +-- .../org/luaj/vm2/compiler/SimpleTests.java | 6 +- .../luaj/vm2/lib/jse/LuaJavaCoercionTest.java | 15 ++-- .../lib/jse/LuajavaAccessibleMembersTest.java | 6 +- 38 files changed, 494 insertions(+), 254 deletions(-) diff --git a/src/core/org/luaj/vm2/Globals.java b/src/core/org/luaj/vm2/Globals.java index 9ce03571..814e958c 100644 --- a/src/core/org/luaj/vm2/Globals.java +++ b/src/core/org/luaj/vm2/Globals.java @@ -32,28 +32,83 @@ import org.luaj.vm2.lib.PackageLib; 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 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 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. + * Global environment used by luaj. Contains global variables referenced by executing lua. *

+ * + *

Constructing and Initializing Instances

* Typically, this is constructed indirectly by a call to * {@link JsePlatform.standardGlobasl()} or {@link JmePlatform.standardGlobals()}, * and then used to load lua scripts for execution as in the following example. * 
 {@code
  * Globals globals = JsePlatform.standardGlobals();
- * globals.compiler.load( new ByteArrayInputStream("print 'hello'".getBytes()), "main.lua", _G ).call();
+ * globals.load( new StringReader("print 'hello'"), "main.lua" ).call(); 
  * }
- * @see LuaCompiler + * The creates a complete global environment with the standard libraries loaded. + *

+ * For specialized circumstances, the Globals may be constructed directly and loaded + * with only those libraries that are needed, for example. + * 

 {@code
+ * Globals globals = new Globals();
+ * globals.load( new BaseLib() ); 
+ * }
+ * + *

Loading and Executing Lua Code

+ * Globals contains convenience functions to load and execute lua source code given a Reader. + * A simple example is: + * 
 {@code
+ * globals.load( new StringReader("print 'hello'"), "main.lua" ).call(); 
+ * }
+ * + *

Fine-Grained Control of Compiling and Loading Lua

+ * Executable LuaFunctions are created from lua code in several steps + * + *

+ * There are alternate flows when the direct lua-to-Java bytecode compiling {@link LuaJC} is used. + *

+ * + *

Java Field

+ * Certain public fields are provided that contain the current values of important global state: + * + * + *

Lua Environment Variables

+ * When using {@link JsePlatform} or {@link JmePlatform}, + * these environment variables are created within the Globals. + * + * + *

Use in Multithreaded Environments

+ * In a multi-threaded server environment, each server thread should create one Globals instance, + * which will be logically distinct and not interfere with each other, but share certain + * static immutable resources such as class data and string data. + *

+ * * @see org.luaj.vm2.lib.jse.JsePlatform * @see org.luaj.vm2.lib.jme.JmePlatform * @see LuaValue - * + * @see Compiler + * @see Loader + * @see Undumper + * @see ResourceFinder + * @see LuaC + * @see LuaJC */ public class Globals extends LuaTable { diff --git a/src/core/org/luaj/vm2/LoadState.java b/src/core/org/luaj/vm2/LoadState.java index f32cb392..e583d509 100644 --- a/src/core/org/luaj/vm2/LoadState.java +++ b/src/core/org/luaj/vm2/LoadState.java @@ -25,35 +25,53 @@ import java.io.DataInputStream; import java.io.IOException; import java.io.InputStream; +import org.luaj.vm2.compiler.DumpState; + /** -* Class to manage loading of {@link Prototype} instances. +* Class to undump compiled lua bytecode into a {@link Prototype} instances. *

-* The {@link LoadState} class exposes one main function, -* namely {@link #load(InputStream, String, LuaValue)}, -* to be used to load code from a particular input stream. +* The {@link LoadState} class implements {@link Globals#Undumper} +* which is used to undump a string of bytes that represent a lua binary file +* using either the C-based lua compiler, or luaj's {@link DumpState#dump} function. *

-* A simple pattern for loading and executing code is +* The canonical method to load and execute code is done +* indirectly using the Globals: * 

 {@code
-* Globals _G = JsePlatform.standardGlobals();
-* _G.load(new FileReader("main.lua"), "main.lua", _G ).call();
+* Globals globals = JsePlatform.standardGlobals();
+* LuaValue chunk = globasl.load("print('hello, world')", "main.lua");
+* chunk.call();
 * }
* This should work regardless of which {@link Globals.Compiler} * has been installed. *

-* -* Prior to loading code, a compiler should be installed. -*

* By default, when using {@link JsePlatform} or {@JmePlatform} -* to construct globals, the {@link LuaC} compiler is installed. +* to construct globals, the {@link LoadState} is installed +* as the default {@link Globals#undumper}. *

-* To override the default compiler with, say, the {@link LuaJC} -* lua-to-java bytecode compiler, install it before loading, -* for example: +* +* A lua binary file is created via {@link DumpState#dump}: * 

 {@code
-* LuaValue _G = JsePlatform.standardGlobals();
-* LuaJC.install(_G);
-* LoadState.load( new FileInputStream("main.lua"), "main.lua", _G ).call();
+* Globals globals = JsePlatform.standardGlobals();
+* Prototype p = globals.compilePrototype(new StringReader("print('hello, world')"), "main.lua");
+* ByteArrayOutputStream o = new ByteArrayOutputStream();
+* DumpState.dump(p, o, false);
+* byte[] lua_binary_file_bytes = o.toByteArray();
+* }
+* +* The {@link LoadState} may be used directly to undump these bytes: +* 
 {@code
+* Prototypep = LoadState.instance.undump(new ByteArrayInputStream(lua_binary_file_bytes), "main.lua");
+* LuaClosure c = new LuaClosure(p, globals);
+* c.call();
+* }
+* +* +* More commonly, the {@link Globals#undumper} may be used to undump them: +* 
 {@code
+* Prototype p = globals.loadPrototype(new ByteArrayInputStream(lua_binary_file_bytes), "main.lua", "b");
+* LuaClosure c = new LuaClosure(p, globals);
+* c.call();
 * }
* * @see LuaCompiler diff --git a/src/core/org/luaj/vm2/LuaClosure.java b/src/core/org/luaj/vm2/LuaClosure.java index cd627116..22e54db2 100644 --- a/src/core/org/luaj/vm2/LuaClosure.java +++ b/src/core/org/luaj/vm2/LuaClosure.java @@ -25,40 +25,39 @@ package org.luaj.vm2; * Extension of {@link LuaFunction} which executes lua bytecode. *

* A {@link LuaClosure} is a combination of a {@link Prototype} - * and a {@link LuaValue} to use as an environment for execution. + * and a {@link LuaValue} to use as an environment for execution. + * Normally the {@link LuaValue} is a {@link Globals} in which case the environment + * will contain standard lua libraries. + * *

* There are three main ways {@link LuaClosure} instances are created: *

*

* To construct it directly, the {@link Prototype} is typically created via a compiler such as {@link LuaC}: * 

 {@code
- * InputStream is = new ByteArrayInputStream("print('hello,world').getBytes());
+ * String script = "print( 'hello, world' )";
+ * InputStream is = new ByteArrayInputStream(script.getBytes());
  * Prototype p = LuaC.instance.compile(is, "script");
- * LuaValue _G = JsePlatform.standardGlobals()
- * LuaClosure f = new LuaClosure(p, _G);
+ * LuaValue globals = JsePlatform.standardGlobals();
+ * LuaClosure f = new LuaClosure(p, globals);
+ * f.call();
  * }
*

- * To construct it indirectly, the {@link LuaC} compiler may be used, - * which implements the {@link LuaCompiler} interface: + * To construct it indirectly, the {@link Globals#load} method may be used: * 

 {@code
- * LuaFunction f = LuaC.instance.load(is, "script", _G);
+ * Globals globals = JsePlatform.standardGlobals();
+ * LuaFunction f = globals.load(new StringReader(script), "script");
+ * LuaClosure c = f.checkclosure();  // This may fail if LuaJC is installed.
+ * c.call();
  * }
*

- * Typically, a closure that has just been loaded needs to be initialized by executing it, - * and its return value can be saved if needed: - * 

 {@code
- * LuaValue r = f.call();
- * _G.set( "mypkg", r ) 
- * }
- *

- * In the preceding, the loaded value is typed as {@link LuaFunction} - * to allow for the possibility of other compilers such as {@link LuaJC} - * producing {@link LuaFunction} directly without - * creating a {@link Prototype} or {@link LuaClosure}. + * In this example, the "checkclosure()" may fail if direct lua-to-java-bytecode + * compiling using LuaJC is installed, because no LuaClosure is created in that case + * and the value returned is a {@link LuaFunction} but not a {@link LuaClosure}. *

* Since a {@link LuaClosure} is a {@link LuaFunction} which is a {@link LuaValue}, * all the value operations can be used directly such as: diff --git a/src/core/org/luaj/vm2/Print.java b/src/core/org/luaj/vm2/Print.java index 07856d4f..39c80f70 100644 --- a/src/core/org/luaj/vm2/Print.java +++ b/src/core/org/luaj/vm2/Print.java @@ -35,6 +35,7 @@ public class Print extends Lua { private static final String STRING_FOR_NULL = "null"; public static PrintStream ps = System.out; + /** String names for each lua opcode value. */ public static final String[] OPNAMES = { "MOVE", "LOADK", @@ -341,21 +342,30 @@ public class Print extends Lua { } } - public static void print(Prototype p) { - printFunction(p, true); + /** Pretty-prints contents of a Prototype. + * + * @param prototype Prototype to print. + */ + public static void print(Prototype prototype) { + printFunction(prototype, true); } - public static void printFunction(Prototype f, boolean full) { - int i, n = f.p.length; - printHeader(f); - printCode(f); + /** Pretty-prints contents of a Prototype in short or long form. + * + * @param prototype Prototype to print. + * @param full true to print all fields, false to print short form. + */ + public static void printFunction(Prototype prototype, boolean full) { + int i, n = prototype.p.length; + printHeader(prototype); + printCode(prototype); if (full) { - printConstants(f); - printLocals(f); - printUpValues(f); + printConstants(prototype); + printLocals(prototype); + printUpValues(prototype); } for (i = 0; i < n; i++) - printFunction(f.p[i], full); + printFunction(prototype.p[i], full); } private static void format( String s, int maxcols ) { diff --git a/src/core/org/luaj/vm2/Prototype.java b/src/core/org/luaj/vm2/Prototype.java index 4f3e1bf0..70f5f2cf 100644 --- a/src/core/org/luaj/vm2/Prototype.java +++ b/src/core/org/luaj/vm2/Prototype.java @@ -23,13 +23,62 @@ package org.luaj.vm2; /** * Prototype representing compiled lua code. + * *

* This is both a straight translation of the corresponding C type, * and the main data structure for execution of compiled lua bytecode. + * *

- * See documentatation on {@link LuaClosure} for information on how to load - * and execute a {@link Prototype}. + * Generally, the {@link Protoytpe} is not constructed directly is an intermediate result + * as lua code is loaded using {@link Globals.load}: + * 

 {@code
+ * Globals globals = JsePlatform.standardGlobals();
+ * globals.load( new StringReader("print 'hello'"), "main.lua" ).call(); 
+ * }
+ * + *

+ * To create a {@link Prototype} directly, a compiler such as {@link LuaC} may be used: + * 

 {@code
+ * InputStream is = new ByteArrayInputStream("print('hello,world')".getBytes());
+ * Prototype p = LuaC.instance.compile(is, "script");
+ * }
+ * + * To simplify loading, the {@link Globals#compilePrototype} method may be used: + * 
 {@code
+ * Prototype p = globals.compileProtoytpe(is, "script");
+ * }
+ * + * It may also be loaded from a {@link java.io.Reader} : + * 
 {@code
+ * Prototype p = globals.compileProtoytpe(new StringReader(script), "script");
+ * }
+ * + * To un-dump a binary file known to be a binary lua file that has been dumped to a string, + * the {@link Globals#Undumper} interface may be used: + * 
 {@code
+ * FileInputStream lua_binary_file = new FileInputStream("foo.lc");  // Known to be compiled lua.
+ * Prototype p = globals.undumper.undump(lua_binary_file, "foo.lua");
+ * }
+ * + * To execute the code represented by the {@link Prototype} it must be supplied to + * the constructor of a {@link LuaClosure}: + * 
 {@code
+ * Globals globals = JsePlatform.standardGlobals();
+ * LuaClosure f = new LuaClosure(p, globals);
+ * f.call();
+ * }
+ * + * To simplify the debugging of prototype values, the contents may be printed using {@link Print#print}: + * 
 {@code
+ * Print.print(p);
+ * }
+ *

+ * * @see LuaClosure + * @see Globals + * @see Globals#Undumper + * @see Globasl#Compiler + * @see Print#print */ public class Prototype { diff --git a/src/core/org/luaj/vm2/compiler/DumpState.java b/src/core/org/luaj/vm2/compiler/DumpState.java index ebf39f02..cc213315 100644 --- a/src/core/org/luaj/vm2/compiler/DumpState.java +++ b/src/core/org/luaj/vm2/compiler/DumpState.java @@ -25,14 +25,48 @@ import java.io.DataOutputStream; import java.io.IOException; import java.io.OutputStream; +import org.luaj.vm2.Globals; import org.luaj.vm2.LoadState; import org.luaj.vm2.LocVars; -import org.luaj.vm2.LuaUserdata; import org.luaj.vm2.Prototype; import org.luaj.vm2.LuaString; import org.luaj.vm2.LuaValue; +/** Class to dump a {@link Prototype} into an output stream, as part of compiling. + *

+ * Generally, this class is not used directly, but rather indirectly via a command + * line interface tool such as {@link luac}. + *

+ * A lua binary file is created via {@link DumpState#dump}: + * 

 {@code
+ * Globals globals = JsePlatform.standardGlobals();
+ * Prototype p = globals.compilePrototype(new StringReader("print('hello, world')"), "main.lua");
+ * ByteArrayOutputStream o = new ByteArrayOutputStream();
+ * DumpState.dump(p, o, false);
+ * byte[] lua_binary_file_bytes = o.toByteArray();
+ * }
+ * + * The {@link LoadState} may be used directly to undump these bytes: + * 
 {@code
+ * Prototypep = LoadState.instance.undump(new ByteArrayInputStream(lua_binary_file_bytes), "main.lua");
+ * LuaClosure c = new LuaClosure(p, globals);
+ * c.call();
+ * }
+ * + * + * More commonly, the {@link Globals#undumper} may be used to undump them: + * 
 {@code
+ * Prototype p = globals.loadPrototype(new ByteArrayInputStream(lua_binary_file_bytes), "main.lua", "b");
+ * LuaClosure c = new LuaClosure(p, globals);
+ * c.call();
+ * }
+ * + * @see luac + * @see LoadState + * @see Globals + * @see Prototype + */ public class DumpState { /** set true to allow integer compilation */ diff --git a/src/core/org/luaj/vm2/compiler/LuaC.java b/src/core/org/luaj/vm2/compiler/LuaC.java index 87cea448..dc14faa3 100644 --- a/src/core/org/luaj/vm2/compiler/LuaC.java +++ b/src/core/org/luaj/vm2/compiler/LuaC.java @@ -39,25 +39,36 @@ import org.luaj.vm2.lib.BaseLib; /** * Compiler for Lua. + * *

* Compiles lua source files into lua bytecode within a {@link Prototype}, * loads lua binary files directly into a{@link Prototype}, * and optionaly instantiates a {@link LuaClosure} around the result * using a user-supplied environment. + * *

* Implements the {@link Globals.Compiler} interface for loading * initialized chunks, which is an interface common to - * lua bytecode compiling and java bytecode compiling. + * lua bytecode compiling and java bytecode compiling. + * *

- * Teh {@link LuaC} compiler is installed by default by both the + * The {@link LuaC} compiler is installed by default by both the * {@link JsePlatform} and {@link JmePlatform} classes, * so in the following example, the default {@link LuaC} compiler * will be used: * 

 {@code
- * LuaValue _G = JsePlatform.standardGlobals();
- * LoadState.load( new ByteArrayInputStream("print 'hello'".getBytes()), "main.lua", _G ).call();
+ * Globals globals = JsePlatform.standardGlobals();
+ * globals.load(new StringReader("print 'hello'"), "main.lua" ).call();
  * }
- * @see LuaCompiler + * + * To load the LuaC compiler manually, use the install method: + * 
 {@code
+ * LuaC.install(globals);
+ * }
+ * + * @see LuaC#install(Globals) + * @see Globals#Compiler + * @see Globals#Loader * @see LuaJC * @see JsePlatform * @see JmePlatform @@ -68,15 +79,17 @@ import org.luaj.vm2.lib.BaseLib; */ public class LuaC extends Lua implements Globals.Compiler, Globals.Loader { + /** A sharable instance of the LuaC compiler. */ public static final LuaC instance = new LuaC(); /** Install the compiler so that LoadState will first * try to use it when handed bytes that are * not already a compiled lua chunk. + * @param globals the Globals into which this is to be installed. */ - public static void install(Globals g) { - g.compiler = instance; - g.loader = instance; + public static void install(Globals globals) { + globals.compiler = instance; + globals.loader = instance; } protected static void _assert(boolean b) { diff --git a/src/core/org/luaj/vm2/lib/BaseLib.java b/src/core/org/luaj/vm2/lib/BaseLib.java index c246def7..28f17145 100644 --- a/src/core/org/luaj/vm2/lib/BaseLib.java +++ b/src/core/org/luaj/vm2/lib/BaseLib.java @@ -23,15 +23,12 @@ package org.luaj.vm2.lib; import java.io.IOException; import java.io.InputStream; -import java.io.PrintStream; import org.luaj.vm2.Globals; -import org.luaj.vm2.LoadState; import org.luaj.vm2.Lua; import org.luaj.vm2.LuaError; import org.luaj.vm2.LuaString; import org.luaj.vm2.LuaTable; -import org.luaj.vm2.LuaThread; import org.luaj.vm2.LuaValue; import org.luaj.vm2.Varargs; @@ -50,15 +47,20 @@ import org.luaj.vm2.Varargs; * directory lookup, use {@link JseBaseLib} instead. *

* Typically, this library is included as part of a call to either + * {@link JsePlatform#standardGlobals()} or * {@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.get("print").call(LuaValue.valueOf("hello, world"));
+ * Globals globals = JsePlatform.standardGlobals();
+ * globals.get("print").call(LuaValue.valueOf("hello, world"));
+ * }
+ *

+ * 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"));
  * }
* Doing so will ensure the library is properly initialized * and loaded into the globals table. @@ -70,7 +72,7 @@ import org.luaj.vm2.Varargs; * @see LibFunction * @see JsePlatform * @see JmePlatform - * @see http://www.lua.org/manual/5.1/manual.html#5.1 + * @see Lua 5.2 Base Lib Reference */ public class BaseLib extends TwoArgFunction implements ResourceFinder { diff --git a/src/core/org/luaj/vm2/lib/Bit32Lib.java b/src/core/org/luaj/vm2/lib/Bit32Lib.java index 71cc2a50..afce847b 100644 --- a/src/core/org/luaj/vm2/lib/Bit32Lib.java +++ b/src/core/org/luaj/vm2/lib/Bit32Lib.java @@ -27,6 +27,29 @@ import org.luaj.vm2.Varargs; /** * Subclass of LibFunction that implements the Lua standard {@code bit32} library. + *

+ * Typically, this library is included as part of a call to either + * {@link JsePlatform#standardGlobals()} or {@link JmePlatform#standardGlobals()} + * 

 {@code
+ * Globals globals = JsePlatform.standardGlobals();
+ * System.out.println( globals.get("bit32").get("bnot").call( LuaValue.valueOf(2) ) );
+ * }
+ *

+ * To instantiate and use it directly, + * link it into your globals table via {@link LuaValue#load(LuaValue)} using code such as: + * 

 {@code
+ * Globals globals = new Globals();
+ * globals.load(new JseBaseLib());
+ * globals.load(new PackageLib());
+ * globals.load(new Bit32Lib());
+ * System.out.println( globals.get("bit32").get("bnot").call( LuaValue.valueOf(2) ) );
+ * }
+ *

+ * 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 Lua 5.2 Bitwise Operation Lib Reference */ public class Bit32Lib extends TwoArgFunction { diff --git a/src/core/org/luaj/vm2/lib/CoroutineLib.java b/src/core/org/luaj/vm2/lib/CoroutineLib.java index 8c8bb298..8790c602 100644 --- a/src/core/org/luaj/vm2/lib/CoroutineLib.java +++ b/src/core/org/luaj/vm2/lib/CoroutineLib.java @@ -40,20 +40,25 @@ import org.luaj.vm2.Varargs; *

* Typically, this library is included as part of a call to either * {@link JsePlatform#standardGlobals()} or {@link JmePlatform#standardGlobals()} + * 

 {@code
+ * Globals globals = JsePlatform.standardGlobals();
+ * System.out.println( globals.get("coroutine").get("running").call() );
+ * }
*

* 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();
- * _G.load(new CoroutineLib());
+ * Globals globals = new Globals();
+ * globals.load(new JseBaseLib());
+ * globals.load(new PackageLib());
+ * globals.load(new CoroutineLib());
+ * System.out.println( globals.get("coroutine").get("running").call() );
  * }
- * Doing so will ensure the library is properly initialized - * and loaded into the globals table. *

* @see LibFunction * @see JsePlatform * @see JmePlatform - * @see http://www.lua.org/manual/5.1/manual.html#5.2 + * @see Lua 5.2 Coroutine Lib Reference */ public class CoroutineLib extends TwoArgFunction { diff --git a/src/core/org/luaj/vm2/lib/DebugLib.java b/src/core/org/luaj/vm2/lib/DebugLib.java index 82fa0857..e6e23947 100644 --- a/src/core/org/luaj/vm2/lib/DebugLib.java +++ b/src/core/org/luaj/vm2/lib/DebugLib.java @@ -50,20 +50,25 @@ import org.luaj.vm2.Varargs; *

* Typically, this library is included as part of a call to either * {@link JsePlatform#debugGlobals()} or {@link JmePlatform#debugGlobals()} + * 

 {@code
+ * Globals globals = JsePlatform.debugGlobals();
+ * System.out.println( globals.get("debug").get("traceback").call() );
+ * }
*

* To instantiate and use it directly, * link it into your globals table via {@link LuaValue#load(LuaValue)} using code such as: * 

 {@code
- * Globals _G = new Globals();
- * _G.load(new DebugLib());
+ * Globals globals = new Globals();
+ * globals.load(new JseBaseLib());
+ * globals.load(new PackageLib());
+ * globals.load(new DebugLib());
+ * System.out.println( globals.get("debug").get("traceback").call() );
  * }
- * Doing so will ensure the library is properly initialized - * and loaded into the globals table. *

* @see LibFunction * @see JsePlatform * @see JmePlatform - * @see http://www.lua.org/manual/5.1/manual.html#5.9 + * @see Lua 5.2 Debug Lib Reference */ public class DebugLib extends TwoArgFunction { public static final boolean CALLS = (null != System.getProperty("CALLS")); diff --git a/src/core/org/luaj/vm2/lib/IoLib.java b/src/core/org/luaj/vm2/lib/IoLib.java index c1aac248..68319b9c 100644 --- a/src/core/org/luaj/vm2/lib/IoLib.java +++ b/src/core/org/luaj/vm2/lib/IoLib.java @@ -47,20 +47,23 @@ import org.luaj.vm2.Varargs; *

* Typically, this library is included as part of a call to either * {@link JsePlatform#standardGlobals()} or {@link JmePlatform#standardGlobals()} + * 

 {@code
+ * Globals globals = JsePlatform.standardGlobals();
+ * globals.get("io").get("write").call(LuaValue.valueOf("hello, world\n"));
+ * }
+ * In this example the platform-specific {@link JseIoLib} library will be loaded, which will include + * the base functionality provided by this class, whereas the {@link JsePlatform} would load the + * {@link JseIoLib}. *

* 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();
- * _G.load(new JseIoLib());
- * 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 = new Globals();
+ * globals.load(new JseBaseLib());
+ * globals.load(new PackageLib());
+ * globals.load(new OsLib());
+ * 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. *

* This has been implemented to match as closely as possible the behavior in the corresponding library in C. * @see LibFunction diff --git a/src/core/org/luaj/vm2/lib/MathLib.java b/src/core/org/luaj/vm2/lib/MathLib.java index 2d975496..e9e43d57 100644 --- a/src/core/org/luaj/vm2/lib/MathLib.java +++ b/src/core/org/luaj/vm2/lib/MathLib.java @@ -51,17 +51,22 @@ import org.luaj.vm2.Varargs; * hand for JME, so will be slower and less accurate than when executed on the JSE platform. *

* Typically, this library is included as part of a call to either - * {@link JmePlatform#standardGlobals()} + * {@link JsePlatform#standardGlobals()} or {@link JmePlatform#standardGlobals()} + * 

 {@code
+ * Globals globals = JsePlatform.standardGlobals();
+ * System.out.println( globals.get("math").get("sqrt").call( LuaValue.valueOf(2) ) );
+ * }
+ * When using {@link JsePlaform} as in this example, the subclass {@link JseMathLib} will + * be included, which also includes this base functionality. *

* 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 MathLib());
- * System.out.println( _G.get("math").get("sqrt").call( LuaValue.valueOf(2) ) );
+ * Globals globals = new Globals();
+ * globals.load(new JseBaseLib());
+ * globals.load(new PackageLib());
+ * globals.load(new MathLib());
+ * System.out.println( globals.get("math").get("sqrt").call( LuaValue.valueOf(2) ) );
  * }
* Doing so will ensure the library is properly initialized * and loaded into the globals table. @@ -71,7 +76,7 @@ import org.luaj.vm2.Varargs; * @see JsePlatform * @see JmePlatform * @see JseMathLib - * @see http://www.lua.org/manual/5.1/manual.html#5.6 + * @see Lua 5.2 Math Lib Reference */ public class MathLib extends TwoArgFunction { diff --git a/src/core/org/luaj/vm2/lib/OsLib.java b/src/core/org/luaj/vm2/lib/OsLib.java index 1e23e112..2ab21878 100644 --- a/src/core/org/luaj/vm2/lib/OsLib.java +++ b/src/core/org/luaj/vm2/lib/OsLib.java @@ -55,20 +55,23 @@ import org.luaj.vm2.Varargs; * *

* Typically, this library is included as part of a call to either - * {@link JmePlatform#standardGlobals()} + * {@link JsePlatform#standardGlobals()} or {@link JmePlatform#standardGlobals()} + * 

 {@code
+ * Globals globals = JsePlatform.standardGlobals();
+ * System.out.println( globals.get("os").get("time").call() );
+ * }
+ * In this example the platform-specific {@link JseOsLib} library will be loaded, which will include + * the base functionality provided by this class. *

* 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 OsLib());
- * System.out.println( _G.get("os").get("time").call() );
+ * Globals globals = new Globals();
+ * globals.load(new JseBaseLib());
+ * globals.load(new PackageLib());
+ * globals.load(new OsLib());
+ * System.out.println( globals.get("os").get("time").call() );
  * }
- * Doing so will ensure the library is properly initialized - * and loaded into the globals table. *

* @see LibFunction * @see JseOsLib diff --git a/src/core/org/luaj/vm2/lib/PackageLib.java b/src/core/org/luaj/vm2/lib/PackageLib.java index bfdae8a3..666c2e4d 100644 --- a/src/core/org/luaj/vm2/lib/PackageLib.java +++ b/src/core/org/luaj/vm2/lib/PackageLib.java @@ -34,37 +34,53 @@ import org.luaj.vm2.Varargs; * Subclass of {@link LibFunction} which implements the lua standard package and module * library functions. * - *

+ *

Lua Environment Variables

+ * The following variables are available to lua scrips when this library has been loaded: + * + * + *

Java Environment Variables

+ * These Java environment variables affect the library behavior: + * + * + *

Loading

* Typically, this library is included as part of a call to either * {@link JsePlatform#standardGlobals()} or {@link JmePlatform#standardGlobals()} + * 
 {@code
+ * Globals globals = JsePlatform.standardGlobals();
+ * System.out.println( globals.get("require").call"foo") );
+ * }
*

* To instantiate and use it directly, * link it into your globals table via {@link LuaValue#load(LuaValue)} using code such as: * 

 {@code
- * Globals _G = new Globals();
- * _G.load(new BaseLib());
- * _G.load(new PackageLib());
- * System.out.println( _G.package_.require.call"foo") );
+ * Globals globals = new Globals();
+ * globals.load(new JseBaseLib());
+ * globals.load(new PackageLib());
+ * System.out.println( globals.get("require").call("foo") );
  * }
- * In practice, the first 3 lines of the above are minimal requirements to get - * and initialize a globals table capable of basic require, print, and other functions, - * so it is much more convenient to use the {@link JsePlatform} and {@link JmePlatform} - * utility classes instead. - *

- * This has been implemented to match as closely as possible the behavior in the corresponding library in C. + *

Limitations

+ * This library has been implemented to match as closely as possible the behavior in the corresponding library in C. * However, the default filesystem search semantics are different and delegated to the bas library * as outlined in the {@link BaseLib} and {@link JseBaseLib} documentation. + *

* @see LibFunction * @see BaseLib * @see JseBaseLib * @see JsePlatform * @see JmePlatform - * @see http://www.lua.org/manual/5.1/manual.html#5.3 + * @see Lua 5.2 Package Lib Reference */ public class PackageLib extends TwoArgFunction { /** The default value to use for package.path. This can be set with the system property - * "luaj.package.path", and is "?.lua" by default. */ + * "luaj.package.path", and is "?.lua" by default. */ public static String DEFAULT_LUA_PATH = System.getProperty("luaj.package.path"); static { if (DEFAULT_LUA_PATH == null) diff --git a/src/core/org/luaj/vm2/lib/StringLib.java b/src/core/org/luaj/vm2/lib/StringLib.java index b56caa3d..756d69b2 100644 --- a/src/core/org/luaj/vm2/lib/StringLib.java +++ b/src/core/org/luaj/vm2/lib/StringLib.java @@ -35,29 +35,29 @@ import org.luaj.vm2.compiler.DumpState; /** * Subclass of {@link LibFunction} which implements the lua standard {@code string} * library. - * *

* Typically, this library is included as part of a call to either * {@link JsePlatform#standardGlobals()} or {@link JmePlatform#standardGlobals()} + * 

 {@code
+ * Globals globals = JsePlatform.standardGlobals();
+ * System.out.println( globals.get("string").get("upper").call( LuaValue.valueOf("abcde") ) );
+ * }
*

* 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 StringLib());
- * System.out.println( _G.get("string").get("upper").call( LuaValue.valueOf("abcde") ) );
+ * Globals globals = new Globals();
+ * globals.load(new JseBaseLib());
+ * globals.load(new PackageLib());
+ * globals.load(new StringLib());
+ * System.out.println( globals.get("string").get("upper").call( LuaValue.valueOf("abcde") ) );
  * }
- * Doing so will ensure the library is properly initialized - * and loaded into the globals table. *

* This is a direct port of the corresponding library in C. * @see LibFunction * @see JsePlatform * @see JmePlatform - * @see http://www.lua.org/manual/5.1/manual.html#5.4 + * @see Lua 5.2 String Lib Reference */ public class StringLib extends TwoArgFunction { diff --git a/src/core/org/luaj/vm2/lib/TableLib.java b/src/core/org/luaj/vm2/lib/TableLib.java index 253be18d..2d07c5d4 100644 --- a/src/core/org/luaj/vm2/lib/TableLib.java +++ b/src/core/org/luaj/vm2/lib/TableLib.java @@ -32,29 +32,26 @@ import org.luaj.vm2.Varargs; *

* Typically, this library is included as part of a call to either * {@link JsePlatform#standardGlobals()} or {@link JmePlatform#standardGlobals()} + * 

 {@code
+ * Globals globals = JsePlatform.standardGlobals();
+ * System.out.println( globals.get("table").get("length").call( LuaValue.tableOf() ) );
+ * }
*

* 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 TableLib());
- * LuaValue tbl = LuaValue.listOf( new LuaValue[] {
- * 		LuaValue.valueOf( "abc" ),
- * 		LuaValue.valueOf( "def" ) } );
- * LuaValue sep = LuaValue.valueOf( "-" );
- * System.out.println( _G.get("table").get("concat").call( tbl, sep ) );
+ * Globals globals = new Globals();
+ * globals.load(new JseBaseLib());
+ * globals.load(new PackageLib());
+ * globals.load(new TableLib());
+ * System.out.println( globals.get("table").get("length").call( LuaValue.tableOf() ) );
  * }
- * Doing so will ensure the library is properly initialized - * and loaded into the globals table. *

* 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 http://www.lua.org/manual/5.1/manual.html#5.5 + * @see Lua 5.2 Table Lib Reference */ public class TableLib extends TwoArgFunction { diff --git a/src/jme/org/luaj/vm2/lib/jme/JmeIoLib.java b/src/jme/org/luaj/vm2/lib/jme/JmeIoLib.java index 3d9de48f..1e135c07 100644 --- a/src/jme/org/luaj/vm2/lib/jme/JmeIoLib.java +++ b/src/jme/org/luaj/vm2/lib/jme/JmeIoLib.java @@ -49,7 +49,7 @@ import org.luaj.vm2.lib.LibFunction; *

* 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: + * directly via {@link Globals#load(LuaValue)} using code such as: * 

 {@code
  * Globals globals = new Globals();
  * globals.load(new JmeBaseLib());
diff --git a/src/jse/lua.java b/src/jse/lua.java
index aa161799..f89719fa 100644
--- a/src/jse/lua.java
+++ b/src/jse/lua.java
@@ -29,9 +29,7 @@ import java.io.InputStreamReader;
 import java.util.Vector;
 
 import org.luaj.vm2.Globals;
-import org.luaj.vm2.LoadState;
 import org.luaj.vm2.Lua;
-import org.luaj.vm2.LuaFunction;
 import org.luaj.vm2.LuaTable;
 import org.luaj.vm2.LuaValue;
 import org.luaj.vm2.Print;
@@ -65,7 +63,7 @@ public class lua {
 		System.exit(-1);		
 	}
 
-	private static Globals _G;
+	private static Globals globals;
 	private static boolean print = false;
 	private static String encoding = null;
 	
@@ -137,8 +135,8 @@ public class lua {
 				System.out.println(version);
 			
 			// new lua state
-			_G = nodebug? JsePlatform.standardGlobals(): JsePlatform.debugGlobals();
-			if ( luajc ) LuaJC.install(_G);
+			globals = nodebug? JsePlatform.standardGlobals(): JsePlatform.debugGlobals();
+			if ( luajc ) LuaJC.install(globals);
 			for ( int i=0, n=libs!=null? libs.size(): 0; i
  * 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:
+ * directly via {@link Globals#load(LuaValue)} using code such as:
  * 
 {@code
  * Globals globals = new Globals();
  * globals.load(new JseBaseLib());
diff --git a/src/jse/org/luaj/vm2/lib/jse/JseMathLib.java b/src/jse/org/luaj/vm2/lib/jse/JseMathLib.java
index fce8c4c7..0b4f2ef8 100644
--- a/src/jse/org/luaj/vm2/lib/jse/JseMathLib.java
+++ b/src/jse/org/luaj/vm2/lib/jse/JseMathLib.java
@@ -35,18 +35,18 @@ import org.luaj.vm2.lib.LibFunction;
  * {@link JsePlatform#standardGlobals()}
  * 
 {@code
  * Globals globals = JsePlatform.standardGlobals();
- * System.out.println( _G.get("math").get("sqrt").call( LuaValue.valueOf(2) ) );
+ * System.out.println( globals.get("math").get("sqrt").call( LuaValue.valueOf(2) ) );
  * } 

  * 

  * 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:
+ * directly via {@link Globals#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) ) );
+ * System.out.println( globals.get("math").get("sqrt").call( LuaValue.valueOf(2) ) );
  * } 

  * 
However, other libraries such as CoroutineLib are not loaded in this case.
  * 

diff --git a/src/jse/org/luaj/vm2/lib/jse/JseOsLib.java b/src/jse/org/luaj/vm2/lib/jse/JseOsLib.java
index 09ea94fb..5f62c51b 100644
--- a/src/jse/org/luaj/vm2/lib/jse/JseOsLib.java
+++ b/src/jse/org/luaj/vm2/lib/jse/JseOsLib.java
@@ -48,18 +48,18 @@ import org.luaj.vm2.lib.LibFunction;
  * {@link JsePlatform#standardGlobals()}
  * 
 {@code
  * Globals globals = JsePlatform.standardGlobals();
- * System.out.println( _G.get("os").get("time").call() );
+ * System.out.println( globals.get("os").get("time").call() );
  * } 

  * 

  * 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:
+ * directly via {@link Globals#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() );
+ * System.out.println( globals.get("os").get("time").call() );
  * } 

  * 
However, other libraries such as MathLib are not loaded in this case.
  * 

diff --git a/src/jse/org/luaj/vm2/lib/jse/LuajavaLib.java b/src/jse/org/luaj/vm2/lib/jse/LuajavaLib.java
index a396f1bb..749bca73 100644
--- a/src/jse/org/luaj/vm2/lib/jse/LuajavaLib.java
+++ b/src/jse/org/luaj/vm2/lib/jse/LuajavaLib.java
@@ -34,7 +34,6 @@ import org.luaj.vm2.LuaValue;
 import org.luaj.vm2.Varargs;
 import org.luaj.vm2.compiler.LuaC;
 import org.luaj.vm2.lib.LibFunction;
-import org.luaj.vm2.lib.PackageLib;
 import org.luaj.vm2.lib.VarArgFunction;
 
 /** 
@@ -43,33 +42,42 @@ import org.luaj.vm2.lib.VarArgFunction;
  * Luajava is an approach to mixing lua and java using simple functions that bind 
  * java classes and methods to lua dynamically.  The API is documented on the 
  * luajava documentation pages.
+ * 
  * 

- * 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()}
+ * 
 {@code
+ * Globals globals = JsePlatform.standardGlobals();
+ * System.out.println( globals.get("luajava").get("bindClass").call( LuaValue.valueOf("java.lang.System") ).invokeMethod("currentTimeMillis") );
+ * } 

  * 

  * To instantiate and use it directly, 
- * link it into your globals table via {@link LuaValue#load(LuaValue)} using code such as:
+ * link it into your globals table via {@link Globals#load} using code such as:
  * 
 {@code
- * LuaTable _G = new LuaTable();
- * LuaThread.setGlobals(_G);
- * LuaC.install();
- * _G.load(new BaseLib());
- * _G.load(new PackageLib());
- * _G.load(new LuajavaLib());
- * _G.get("load").call( LuaValue.valueOf( 
- * 		"sys = luajava.bindClass('java.lang.System')\n"+
- * 		"print ( sys:currentTimeMillis() )\n" ) ).call(); 
+ * Globals globals = new Globals();
+ * globals.load(new JseBaseLib());
+ * globals.load(new PackageLib());
+ * globals.load(new LuajavaLib());
+ * globals.load( 
+ *      "sys = luajava.bindClass('java.lang.System')\n"+
+ *      "print ( sys:currentTimeMillis() )\n", "main.lua" ).call(); 
  * } 

- * This example is not intended to be realistic - only to show how the {@link LuajavaLib} 
- * may be initialized by hand.  In practice, the {@code luajava} library is available 
+ * 

+ * 
+ * The {@code luajava} library is available 
  * on all JSE platforms via the call to {@link JsePlatform#standardGlobals()}
- * and the luajava api's are simply invoked from lua.    
+ * and the luajava api's are simply invoked from lua.  
+ * Because it makes extensive use of Java's reflection API, it is not available 
+ * on JME, but can be used in Android applications.
  * 

  * This has been implemented to match as closely as possible the behavior in the corresponding library in C.
+ * 
  * @see LibFunction
  * @see org.luaj.vm2.lib.jse.JsePlatform
  * @see org.luaj.vm2.lib.jme.JmePlatform
  * @see LuaC
+ * @see CoerceJavaToLua
+ * @see CoerceLuaToJava
  * @see http://www.keplerproject.org/luajava/manual.html#luareference
  */
 public class LuajavaLib extends VarArgFunction {
diff --git a/src/jse/org/luaj/vm2/luajc/LuaJC.java b/src/jse/org/luaj/vm2/luajc/LuaJC.java
index aec75906..c65dc268 100644
--- a/src/jse/org/luaj/vm2/luajc/LuaJC.java
+++ b/src/jse/org/luaj/vm2/luajc/LuaJC.java
@@ -27,6 +27,7 @@ import java.io.Reader;
 import java.util.Hashtable;
 
 import org.luaj.vm2.Globals;
+import org.luaj.vm2.LoadState;
 import org.luaj.vm2.LuaFunction;
 import org.luaj.vm2.LuaValue;
 import org.luaj.vm2.Prototype;
@@ -37,19 +38,25 @@ import org.luaj.vm2.lib.BaseLib;
  * Implementation of {@link LuaCompiler} which does direct 
  * lua-to-java-bytecode compiling. 
  * 

+ * By default, when using {@link JsePlatform} or {@JmePlatform}
+ * to construct globals, the plain compiler {@link LuaC} is installed and lua code 
+ * will only be compiled into lua bytecode and execute as {@link LuaClosure}. 
+ * 

+ * To override the default compiling behavior with {@link LuaJC}
+ * lua-to-java bytecode compiler, install it before undumping code, 
+ * for example:
+ * 
 {@code
+ * LuaValue globals = JsePlatform.standardGlobals();
+ * LuaJC.install(globals);
+ * LuaValue chunk = globals.load( "print('hello, world'), "main.lua");
+ * System.out.println(chunk.isclosure());  // Will be false when LuaJC is working.
+ * chunk.call();
+ * } 

+ * 

  * This requires the bcel library to be on the class path to work as expected.  
  * If the library is not found, the default {@link LuaC} lua-to-lua-bytecode 
  * compiler will be used.  
- * 

- * The compiler should be installed as part of globals initialization, 
- * and before any scripts or lua code is executed. 
- * A typical example is to install it following the globals creation, 
- * as in the following:
- * 
 {@code
- * LuaValue _G = JsePlatform.standardGlobals();
- * LuaJC.install(_G);
- * _G.loadString("print 'hello'").call();
- * } 

+ * 
  * @see LuaCompiler
  * @see LuaC
  * @see BaseLib
diff --git a/src/jse/org/luaj/vm2/luajc/ProtoInfo.java b/src/jse/org/luaj/vm2/luajc/ProtoInfo.java
index d9dcaac5..0d33f00a 100644
--- a/src/jse/org/luaj/vm2/luajc/ProtoInfo.java
+++ b/src/jse/org/luaj/vm2/luajc/ProtoInfo.java
@@ -3,7 +3,6 @@ package org.luaj.vm2.luajc;
 import java.io.ByteArrayOutputStream;
 import java.io.PrintStream;
 import java.util.Hashtable;
-import java.util.Vector;
 
 import org.luaj.vm2.Lua;
 import org.luaj.vm2.LuaString;
diff --git a/test/java/org/luaj/luajc/TestLuaJ.java b/test/java/org/luaj/luajc/TestLuaJ.java
index 2c670577..eee17c5c 100644
--- a/test/java/org/luaj/luajc/TestLuaJ.java
+++ b/test/java/org/luaj/luajc/TestLuaJ.java
@@ -47,10 +47,10 @@ public class TestLuaJ {
 		System.out.println(script);
 		
 		// create an environment to run in
-		Globals _G = JsePlatform.standardGlobals();
+		Globals globals = JsePlatform.standardGlobals();
 		
 		// compile into a chunk, or load as a class
-		LuaValue chunk = _G.load(script, "script");
+		LuaValue chunk = globals.load(script, "script");
 		
 		// The loaded chunk should be a closure, which contains the prototype.
 		print( chunk.checkclosure().p );
diff --git a/test/java/org/luaj/luajc/TestLuaJC.java b/test/java/org/luaj/luajc/TestLuaJC.java
index b7650244..91be4a76 100644
--- a/test/java/org/luaj/luajc/TestLuaJC.java
+++ b/test/java/org/luaj/luajc/TestLuaJC.java
@@ -39,7 +39,7 @@ public class TestLuaJC {
 	// build path.  This allows the debugger to find the file when stepping into the function.
 	public static String filename = "perf/nsieve.lua";
 
-	static Globals _G;
+	static Globals globals;
 	
 	public static void main(String[] args) throws Exception {
 		if (args.length > 0)
@@ -48,17 +48,17 @@ public class TestLuaJC {
 		try {
 			
 			// create an environment to run in
-			_G = JsePlatform.standardGlobals();
+			globals = JsePlatform.standardGlobals();
 
 			// print the chunk as a closure, and pretty-print the closure.
-			LuaValue f = _G.loadfile(filename).arg1();
+			LuaValue f = globals.loadfile(filename).arg1();
 			Prototype p = f.checkclosure().p;
 			Print.print(p);
 
 			// load into a luajc java-bytecode based chunk by installing the LuaJC compiler first
 			if ( ! (args.length>0 && args[0].equals("nocompile")) ) {
-				LuaJC.install(_G);
-				f = _G.loadfile(filename).arg1();
+				LuaJC.install(globals);
+				f = globals.loadfile(filename).arg1();
 			}
 	
 			// call with arguments
@@ -79,8 +79,8 @@ public class TestLuaJC {
         // create the chunk
 		String destdir = ".";
 		
-		InputStream is = _G.FINDER.findResource(filename);
-		Hashtable t = LuaJC.instance.compileAll(is, filename, filename, _G, true);
+		InputStream is = globals.FINDER.findResource(filename);
+		Hashtable t = LuaJC.instance.compileAll(is, filename, filename, globals, true);
 
         // write out the chunk
     	for ( Enumeration e = t.keys(); e.hasMoreElements(); ) {
diff --git a/test/junit/org/luaj/vm2/FragmentsTest.java b/test/junit/org/luaj/vm2/FragmentsTest.java
index ab33ba29..c8784f24 100644
--- a/test/junit/org/luaj/vm2/FragmentsTest.java
+++ b/test/junit/org/luaj/vm2/FragmentsTest.java
@@ -64,17 +64,17 @@ public class FragmentsTest extends TestSuite {
 		public void runFragment( Varargs expected, String script ) {
 			try {
 				String name = getName();
-				Globals _G = JsePlatform.debugGlobals();
+				Globals globals = JsePlatform.debugGlobals();
 				Reader reader = new StringReader(script);
 				LuaValue chunk ;
 				switch ( TEST_TYPE ) {
 				case TEST_TYPE_LUAJC:
-					LuaJC.install(_G);
-					chunk = _G.load(reader, name);
+					LuaJC.install(globals);
+					chunk = globals.load(reader, name);
 					break;
 				default:
-					Prototype p = _G.compilePrototype(reader, name);
-					chunk = new LuaClosure(p, _G);
+					Prototype p = globals.compilePrototype(reader, name);
+					chunk = new LuaClosure(p, globals);
 					Print.print(p);
 					break;
 				}
diff --git a/test/junit/org/luaj/vm2/LuaOperationsTest.java b/test/junit/org/luaj/vm2/LuaOperationsTest.java
index 03d0144c..84231586 100644
--- a/test/junit/org/luaj/vm2/LuaOperationsTest.java
+++ b/test/junit/org/luaj/vm2/LuaOperationsTest.java
@@ -130,9 +130,9 @@ public class LuaOperationsTest extends TestCase {
 
 	public Prototype createPrototype( String script, String name ) {
 		try {
-			Globals _G = org.luaj.vm2.lib.jse.JsePlatform.standardGlobals();
+			Globals globals = org.luaj.vm2.lib.jse.JsePlatform.standardGlobals();
 			Reader reader = new StringReader(script);
-			return _G.compilePrototype(reader, name);
+			return globals.compilePrototype(reader, name);
 		} catch (Exception e) {
 			// TODO Auto-generated catch block
 			e.printStackTrace();
@@ -146,25 +146,25 @@ public class LuaOperationsTest extends TestCase {
 		// set up suitable environments for execution
 		LuaValue aaa = LuaValue.valueOf("aaa");
 		LuaValue eee = LuaValue.valueOf("eee");
-		final Globals _G = org.luaj.vm2.lib.jse.JsePlatform.standardGlobals();
+		final Globals globals = org.luaj.vm2.lib.jse.JsePlatform.standardGlobals();
 		LuaTable newenv = LuaValue.tableOf( new LuaValue[] { 
 				LuaValue.valueOf("a"), LuaValue.valueOf("aaa"), 
 				LuaValue.valueOf("b"), LuaValue.valueOf("bbb"), } );
-		LuaTable mt = LuaValue.tableOf( new LuaValue[] { LuaValue.INDEX, _G } );
+		LuaTable mt = LuaValue.tableOf( new LuaValue[] { LuaValue.INDEX, globals } );
 		newenv.setmetatable(mt);
-		_G.set("a", aaa);
+		globals.set("a", aaa);
 		newenv.set("a", eee);
 
 		// function tests
 		{
-			LuaFunction f = new ZeroArgFunction() { public LuaValue call() { return _G.get("a");}};
+			LuaFunction f = new ZeroArgFunction() { public LuaValue call() { return globals.get("a");}};
 			assertEquals( aaa, f.call() );
 		}
 		
 		// closure tests
 		{
 			Prototype p = createPrototype( "return a\n", "closuretester" );
-			LuaClosure c = new LuaClosure(p, _G);
+			LuaClosure c = new LuaClosure(p, globals);
 			
 			// Test that a clusure with a custom enviroment uses that environment.
 			assertEquals( aaa, c.call() );
diff --git a/test/junit/org/luaj/vm2/ScriptDrivenTest.java b/test/junit/org/luaj/vm2/ScriptDrivenTest.java
index 3e0860a4..10828595 100644
--- a/test/junit/org/luaj/vm2/ScriptDrivenTest.java
+++ b/test/junit/org/luaj/vm2/ScriptDrivenTest.java
@@ -177,7 +177,7 @@ public class ScriptDrivenTest extends TestCase implements ResourceFinder {
 		}
 	}
 
-	protected LuaValue loadScript(String name, Globals _G) throws IOException {
+	protected LuaValue loadScript(String name, Globals globals) throws IOException {
 		InputStream script = this.findResource(name+".lua");
 		if ( script == null )
 			fail("Could not load script for test case: " + name);
@@ -188,11 +188,11 @@ public class ScriptDrivenTest extends TestCase implements ResourceFinder {
 					LuaValue c = (LuaValue) Class.forName(name).newInstance();
 					return c;
 				} else {
-					LuaJC.install(_G);
-					return _G.load(script, name, "bt", _G);
+					LuaJC.install(globals);
+					return globals.load(script, name, "bt", globals);
 				}
 			default:
-				return _G.load(script, "@"+name+".lua", "bt", _G);
+				return globals.load(script, "@"+name+".lua", "bt", globals);
 			}
 		} catch ( Exception e ) {
 			e.printStackTrace();
diff --git a/test/junit/org/luaj/vm2/compiler/AbstractUnitTests.java b/test/junit/org/luaj/vm2/compiler/AbstractUnitTests.java
index 8f8de5e3..dd29a9cb 100644
--- a/test/junit/org/luaj/vm2/compiler/AbstractUnitTests.java
+++ b/test/junit/org/luaj/vm2/compiler/AbstractUnitTests.java
@@ -21,7 +21,7 @@ abstract public class AbstractUnitTests extends TestCase {
 
     private final String dir;
     private final String jar;
-    private Globals _G;
+    private Globals globals;
 
     public AbstractUnitTests(String zipdir, String zipfile, String dir) {
     	URL zip = null;
@@ -43,7 +43,7 @@ abstract public class AbstractUnitTests extends TestCase {
 
     protected void setUp() throws Exception {
         super.setUp();
-        _G = JsePlatform.standardGlobals();
+        globals = JsePlatform.standardGlobals();
     }
 
     protected String pathOfFile(String file) {
@@ -67,7 +67,7 @@ abstract public class AbstractUnitTests extends TestCase {
 
             // compile in memory
             InputStream is = new ByteArrayInputStream(lua);
-            Prototype p = _G.loadPrototype(is, "@" + file, "bt");
+            Prototype p = globals.loadPrototype(is, "@" + file, "bt");
             String actual = protoToString(p);
 
             // load expected value from jar
@@ -109,7 +109,7 @@ abstract public class AbstractUnitTests extends TestCase {
     protected Prototype loadFromBytes(byte[] bytes, String script)
             throws IOException {
         InputStream is = new ByteArrayInputStream(bytes);
-        return _G.loadPrototype(is, script, "b");
+        return globals.loadPrototype(is, script, "b");
     }
 
     protected String protoToString(Prototype p) {
diff --git a/test/junit/org/luaj/vm2/compiler/DumpLoadEndianIntTest.java b/test/junit/org/luaj/vm2/compiler/DumpLoadEndianIntTest.java
index 00c6d776..69437a58 100644
--- a/test/junit/org/luaj/vm2/compiler/DumpLoadEndianIntTest.java
+++ b/test/junit/org/luaj/vm2/compiler/DumpLoadEndianIntTest.java
@@ -30,11 +30,11 @@ public class DumpLoadEndianIntTest extends TestCase {
 	private static final String withdoubles = "1234-#!-23.75";
 	private static final String withints = "1234-#!-23";
 
-    private Globals _G;
+    private Globals globals;
 
     protected void setUp() throws Exception {
         super.setUp();
-        _G = JsePlatform.standardGlobals();
+        globals = JsePlatform.standardGlobals();
         DumpState.ALLOW_INTEGER_CASTING = false;
     }
 
@@ -86,10 +86,10 @@ public class DumpLoadEndianIntTest extends TestCase {
             
             // compile into prototype
             Reader reader = new StringReader(script);
-            Prototype p = _G.compilePrototype(reader, "script");
+            Prototype p = globals.compilePrototype(reader, "script");
             
             // double check script result before dumping
-            LuaFunction f = new LuaClosure(p, _G);
+            LuaFunction f = new LuaClosure(p, globals);
             LuaValue r = f.call();
             String actual = r.tojstring();
             assertEquals( expectedPriorDump, actual );
@@ -110,7 +110,7 @@ public class DumpLoadEndianIntTest extends TestCase {
             
             // load again using compiler
             InputStream is = new ByteArrayInputStream(dumped);
-            f = _G.load(is, "dumped", "b", _G).checkfunction();
+            f = globals.load(is, "dumped", "b", globals).checkfunction();
             r = f.call();
             actual = r.tojstring();
             assertEquals( expectedPostDump, actual );
diff --git a/test/junit/org/luaj/vm2/compiler/SimpleTests.java b/test/junit/org/luaj/vm2/compiler/SimpleTests.java
index 638f4c34..993a9861 100644
--- a/test/junit/org/luaj/vm2/compiler/SimpleTests.java
+++ b/test/junit/org/luaj/vm2/compiler/SimpleTests.java
@@ -10,16 +10,16 @@ import org.luaj.vm2.lib.jse.JsePlatform;
 
 public class SimpleTests extends TestCase {
 
-	private Globals _G;
+	private Globals globals;
 
     protected void setUp() throws Exception {
         super.setUp();
-        _G = JsePlatform.standardGlobals();
+        globals = JsePlatform.standardGlobals();
     }
 
     private void doTest( String script ) {
     	try {
-			LuaValue c = _G.load(script, "script");
+			LuaValue c = globals.load(script, "script");
 			c.call();
     	} catch ( Exception e ) {
     		fail("i/o exception: "+e );
diff --git a/test/junit/org/luaj/vm2/lib/jse/LuaJavaCoercionTest.java b/test/junit/org/luaj/vm2/lib/jse/LuaJavaCoercionTest.java
index 5db90743..623db069 100644
--- a/test/junit/org/luaj/vm2/lib/jse/LuaJavaCoercionTest.java
+++ b/test/junit/org/luaj/vm2/lib/jse/LuaJavaCoercionTest.java
@@ -6,13 +6,12 @@ import org.luaj.vm2.LuaError;
 import org.luaj.vm2.LuaInteger;
 import org.luaj.vm2.LuaString;
 import org.luaj.vm2.LuaTable;
-import org.luaj.vm2.LuaUserdata;
 import org.luaj.vm2.LuaValue;
 import org.luaj.vm2.Varargs;
 
 public class LuaJavaCoercionTest extends TestCase {
 
-	private static LuaValue _G;
+	private static LuaValue globals;
 	private static LuaValue ZERO   = LuaValue.ZERO;
 	private static LuaValue ONE   = LuaValue.ONE;
 	private static LuaValue TWO   = LuaValue.valueOf(2);
@@ -21,7 +20,7 @@ public class LuaJavaCoercionTest extends TestCase {
 	
 	protected void setUp() throws Exception {
 		super.setUp();
-		_G = JsePlatform.standardGlobals();
+		globals = JsePlatform.standardGlobals();
 	}
 	
 	public void testJavaIntToLuaInt() {
@@ -220,7 +219,7 @@ public class LuaJavaCoercionTest extends TestCase {
 	public void testExceptionMessage() {
 		String script = "local c = luajava.bindClass( \""+SomeClass.class.getName()+"\" )\n" +
 				"return pcall( c.someMethod, c )";
-		Varargs vresult = _G.get("load").call(LuaValue.valueOf(script)).invoke(LuaValue.NONE);
+		Varargs vresult = globals.get("load").call(LuaValue.valueOf(script)).invoke(LuaValue.NONE);
 		LuaValue status = vresult.arg1();
 		LuaValue message = vresult.arg(2);
 		assertEquals( LuaValue.FALSE, status );		
@@ -230,7 +229,7 @@ public class LuaJavaCoercionTest extends TestCase {
 
 	public void testLuaErrorCause() {
 		String script = "luajava.bindClass( \""+SomeClass.class.getName()+"\"):someMethod()";
-		LuaValue chunk = _G.get("load").call(LuaValue.valueOf(script));
+		LuaValue chunk = globals.get("load").call(LuaValue.valueOf(script));
 		try {
 			chunk.invoke(LuaValue.NONE);
 			fail( "call should not have succeeded" );
@@ -259,7 +258,7 @@ public class LuaJavaCoercionTest extends TestCase {
 			"			) or '-nil')\n" +
 			"	end,\n" +
 			"} )\n";
-		Varargs chunk = _G.get("load").call(LuaValue.valueOf(script));
+		Varargs chunk = globals.get("load").call(LuaValue.valueOf(script));
 		if ( ! chunk.arg1().toboolean() )
 			fail( chunk.arg(2).toString() );
 		LuaValue result = chunk.arg1().call();
@@ -284,7 +283,7 @@ public class LuaJavaCoercionTest extends TestCase {
 			//"print(bigNumB:toString())\n" +
 			//"print(bigNumC:toString())\n" +
 			"return bigNumA:toString(), bigNumB:toString(), bigNumC:toString()";
-		Varargs chunk = _G.get("load").call(LuaValue.valueOf(script));
+		Varargs chunk = globals.get("load").call(LuaValue.valueOf(script));
 		if ( ! chunk.arg1().toboolean() )
 			fail( chunk.arg(2).toString() );
 		Varargs results = chunk.arg1().invoke();
@@ -369,7 +368,7 @@ public class LuaJavaCoercionTest extends TestCase {
 			"local b = a:set(a:get"+typename+"())\n" +
 			"local c = a:setr(a:get"+typename+"())\n" +
 			"return b,c";
-		Varargs chunk = _G.get("load").call(LuaValue.valueOf(script));
+		Varargs chunk = globals.get("load").call(LuaValue.valueOf(script));
 		if ( ! chunk.arg1().toboolean() )
 			fail( chunk.arg(2).toString() );
 		Varargs results = chunk.arg1().invoke();
diff --git a/test/junit/org/luaj/vm2/lib/jse/LuajavaAccessibleMembersTest.java b/test/junit/org/luaj/vm2/lib/jse/LuajavaAccessibleMembersTest.java
index c0dccfe4..2125d0a5 100644
--- a/test/junit/org/luaj/vm2/lib/jse/LuajavaAccessibleMembersTest.java
+++ b/test/junit/org/luaj/vm2/lib/jse/LuajavaAccessibleMembersTest.java
@@ -7,16 +7,16 @@ import org.luaj.vm2.LuaValue;
 
 public class LuajavaAccessibleMembersTest extends TestCase {
 		
-	private Globals _G;
+	private Globals globals;
 
     protected void setUp() throws Exception {
         super.setUp();
-        _G = JsePlatform.standardGlobals();
+        globals = JsePlatform.standardGlobals();
      }
 
     private String invokeScript(String script) {
     	try {
-			LuaValue c = _G.load(script, "script");
+			LuaValue c = globals.load(script, "script");
 			return c.call().tojstring();
     	} catch ( Exception e ) {
     		fail("exception: "+e );