Update javadoc comments related to library initialization and loading lua code.

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.
+ * Global environment used by luaj.  Contains global variables referenced by executing lua.
- * <p>
- * 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.  
- * <p>
- * 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.
  * <p>
+ * 
+ * <h3>Constructing and Initializing Instances</h3>
  * 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. 
  * <pre> {@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(); 
  * } </pre>
- * @see LuaCompiler
+ * The creates a complete global environment with the standard libraries loaded.
+ * <p>
+ * For specialized circumstances, the Globals may be constructed directly and loaded
+ * with only those libraries that are needed, for example.
+ * <pre> {@code
+ * Globals globals = new Globals();
+ * globals.load( new BaseLib() ); 
+ * } </pre>
+ * 
+ * <h3>Loading and Executing Lua Code</h3>
+ * Globals contains convenience functions to load and execute lua source code given a Reader. 
+ * A simple example is:
+ * <pre> {@code
+ * globals.load( new StringReader("print 'hello'"), "main.lua" ).call(); 
+ * } </pre>
+ * 
+ * <h3>Fine-Grained Control of Compiling and Loading Lua</h3>
+ * Executable LuaFunctions are created from lua code in several steps
+ * <ul>
+ * <li>find the resource using the platform's {@link ResourceFinder}
+ * <li>compile lua to lua bytecode using {@link Compiler}
+ * <li>load lua bytecode to a {@link LuaPrototpye} using {@link Undumper}
+ * <li>construct {@link LuaClosure} from {@link Prototype} with {@link Globals} using {@link Loader}
+ * </ul>
+ * <p>
+ * There are alternate flows when the direct lua-to-Java bytecode compiling {@link LuaJC} is used.
+ * <ul>
+ * <li>compile lua to lua bytecode using {@link Compiler} or load precompiled code using {@link Undumper}
+ * <li>convert lua bytecode to equivalent Java bytecode using {@link LuaJC} that implements {@link Loader} directly
+ * </ul>
+ * 
+ * <h3>Java Field</h3>
+ * Certain public fields are provided that contain the current values of important global state:
+ * <ul>
+ * <li>{@link STDIN} Current value for standard input in the laaded IoLib, if any.
+ * <li>{@link STDOUT} Current value for standard output in the loaded IoLib, if any.
+ * <li>{@link STDERR} Current value for standard error in the loaded IoLib, if any.
+ * <li>{@link FINDER} Current loaded {@link ResourceFinder}, if any.
+ * <li>{@link compiler} Current loaded {@link Compiler}, if any.
+ * <li>{@link undumper} Current loaded {@link Undumper}, if any.
+ * <li>{@link loader} Current loaded {@link Loader}, if any.
+ * </ul>
+ * 
+ * <h3>Lua Environment Variables</h3>
+ * When using {@link JsePlatform} or {@link JmePlatform}, 
+ * these environment variables are created within the Globals.
+ * <ul>
+ * <li>"_G" Pointer to this Globals.
+ * <li>"_VERSION" String containing the version of luaj.
+ * </ul>
+ * 
+ * <h3>Use in Multithreaded Environments</h3>
+ * 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.
+ * <p>
+ * 
  * @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 {
 

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.
 * <p>
-* The {@link LoadState} class exposes one main function, 
+* The {@link LoadState} class implements {@link Globals#Undumper}
-* namely {@link #load(InputStream, String, LuaValue)}, 
+* which is used to undump a string of bytes that represent a lua binary file
-* to be used to load code from a particular input stream.  
+* using either the C-based lua compiler, or luaj's {@link DumpState#dump} function.
 * <p>
-* A simple pattern for loading and executing code is
+* The canonical method to load and execute code is done 
+* indirectly using the Globals:
 * <pre> {@code
-* Globals _G = JsePlatform.standardGlobals();
+* Globals globals = JsePlatform.standardGlobals();
-* _G.load(new FileReader("main.lua"), "main.lua", _G ).call();
+* LuaValue chunk = globasl.load("print('hello, world')", "main.lua");
+* chunk.call();
 * } </pre>
 * This should work regardless of which {@link Globals.Compiler}
 * has been installed.
 * <p>
-*  
-* Prior to loading code, a compiler should be installed. 
-* <p>
 * 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}. 
 * <p>
-* To override the default compiler with, say, the {@link LuaJC}
+* 
-* lua-to-java bytecode compiler, install it before loading, 
+* A lua binary file is created via {@link DumpState#dump}:
-* for example:
 * <pre> {@code
-* LuaValue _G = JsePlatform.standardGlobals();
+* Globals globals = JsePlatform.standardGlobals();
-* LuaJC.install(_G);
+* Prototype p = globals.compilePrototype(new StringReader("print('hello, world')"), "main.lua");
-* LoadState.load( new FileInputStream("main.lua"), "main.lua", _G ).call();
+* ByteArrayOutputStream o = new ByteArrayOutputStream();
+* DumpState.dump(p, o, false);
+* byte[] lua_binary_file_bytes = o.toByteArray();
+* } </pre>
+* 
+* The {@link LoadState} may be used directly to undump these bytes:
+* <pre> {@code
+* Prototypep = LoadState.instance.undump(new ByteArrayInputStream(lua_binary_file_bytes), "main.lua");
+* LuaClosure c = new LuaClosure(p, globals);
+* c.call();
+* } </pre>
+* 
+* 
+* More commonly, the {@link Globals#undumper} may be used to undump them:
+* <pre> {@code
+* Prototype p = globals.loadPrototype(new ByteArrayInputStream(lua_binary_file_bytes), "main.lua", "b");
+* LuaClosure c = new LuaClosure(p, globals);
+* c.call();
 * } </pre>
 * 
 * @see LuaCompiler

src/core/org/luaj/vm2/LuaClosure.java

@@ -26,39 +26,38 @@ package org.luaj.vm2;
  * <p>
  * A {@link LuaClosure} is a combination of a {@link Prototype} 
  * 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. 
+ * 
  * <p>
  * There are three main ways {@link LuaClosure} instances are created:
  * <ul> 
  * <li>Construct an instance using {@link #LuaClosure(Prototype, LuaValue)}</li>
- * <li>Construct it indirectly by loading a chunk via {@link LuaCompiler#load(java.io.InputStream, String, LuaValue)}
+ * <li>Construct it indirectly by loading a chunk via {@link Globals#load(java.io.Reader, String, LuaValue)}
  * <li>Execute the lua bytecode {@link Lua#OP_CLOSURE} as part of bytecode processing
  * </ul>
  * <p>
  * To construct it directly, the {@link Prototype} is typically created via a compiler such as {@link LuaC}:
  * <pre> {@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()
+ * LuaValue globals = JsePlatform.standardGlobals();
- * LuaClosure f = new LuaClosure(p, _G);
+ * LuaClosure f = new LuaClosure(p, globals);
+ * f.call();
  * }</pre> 
  * <p>
- * To construct it indirectly, the {@link LuaC} compiler may be used, 
+ * To construct it indirectly, the {@link Globals#load} method may be used: 
- * which implements the {@link LuaCompiler} interface: 
  * <pre> {@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();
  * }</pre>
  * <p>
- * Typically, a closure that has just been loaded needs to be initialized by executing it, 
+ * In this example, the "checkclosure()" may fail if direct lua-to-java-bytecode 
- * and its return value can be saved if needed:
+ * compiling using LuaJC is installed, because no LuaClosure is created in that case
- * <pre> {@code
+ * and the value returned is a {@link LuaFunction} but not a {@link LuaClosure}.
- * LuaValue r = f.call();
- * _G.set( "mypkg", r ) 
- * }</pre>
- * <p> 
- * 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}.
  * <p> 
  * Since a {@link LuaClosure} is a {@link LuaFunction} which is a {@link LuaValue}, 
  * all the value operations can be used directly such as:

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) {
+	/** Pretty-prints contents of a Prototype.
-		printFunction(p, true);
+	 * 
+	 * @param prototype Prototype to print.
+	 */
+	public static void print(Prototype prototype) {
+		printFunction(prototype, true);
 	}
 	
-	public static void printFunction(Prototype f, boolean full) {
+	/** Pretty-prints contents of a Prototype in short or long form.
-		int i, n = f.p.length;
+	 * 
-		printHeader(f);
+	 * @param prototype Prototype to print.
-		printCode(f);
+	 * @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);
+			printConstants(prototype);
-			printLocals(f);
+			printLocals(prototype);
-			printUpValues(f);
+			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 ) {

src/core/org/luaj/vm2/Prototype.java

@@ -23,13 +23,62 @@ package org.luaj.vm2;
 
 /**
  * Prototype representing compiled lua code. 
+ * 
  * <p>
  * This is both a straight translation of the corresponding C type, 
  * and the main data structure for execution of compiled lua bytecode. 
+ * 
  * <p>
- * See documentatation on {@link LuaClosure} for information on how to load 
+ * Generally, the {@link Protoytpe} is not constructed directly is an intermediate result
- * and execute a {@link Prototype}.
+ * as lua code is loaded using {@link Globals.load}:
+ * <pre> {@code
+ * Globals globals = JsePlatform.standardGlobals();
+ * globals.load( new StringReader("print 'hello'"), "main.lua" ).call(); 
+ * } </pre>
+ * 
+ * <p>
+ * To create a {@link Prototype} directly, a compiler such as {@link LuaC} may be used:
+ * <pre> {@code
+ * InputStream is = new ByteArrayInputStream("print('hello,world')".getBytes());
+ * Prototype p = LuaC.instance.compile(is, "script");
+ * }</pre> 
+ * 
+ * To simplify loading, the {@link Globals#compilePrototype} method may be used: 
+ * <pre> {@code
+ * Prototype p = globals.compileProtoytpe(is, "script");
+ * }</pre>
+ * 
+ * It may also be loaded from a {@link java.io.Reader} : 
+ * <pre> {@code
+ * Prototype p = globals.compileProtoytpe(new StringReader(script), "script");
+ * }</pre>
+ * 
+ * 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: 
+ * <pre> {@code
+ * FileInputStream lua_binary_file = new FileInputStream("foo.lc");  // Known to be compiled lua.
+ * Prototype p = globals.undumper.undump(lua_binary_file, "foo.lua");
+ * }</pre>
+ * 
+ * To execute the code represented by the {@link Prototype} it must be supplied to 
+ * the constructor of a {@link LuaClosure}:
+ * <pre> {@code
+ * Globals globals = JsePlatform.standardGlobals();
+ * LuaClosure f = new LuaClosure(p, globals);
+ * f.call();
+ * }</pre> 
+ * 
+ * To simplify the debugging of prototype values, the contents may be printed using {@link Print#print}:
+ * <pre> {@code
+ * Print.print(p);
+ * }</pre>
+ * <p>
+ *  
  * @see LuaClosure
+ * @see Globals
+ * @see Globals#Undumper
+ * @see Globasl#Compiler
+ * @see Print#print
  */
 
 public class Prototype {

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.
+ * <p>
+ * Generally, this class is not used directly, but rather indirectly via a command 
+ * line interface tool such as {@link luac}.
+ * <p>
+ * A lua binary file is created via {@link DumpState#dump}:
+ * <pre> {@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();
+ * } </pre>
+ * 
+ * The {@link LoadState} may be used directly to undump these bytes:
+ * <pre> {@code
+ * Prototypep = LoadState.instance.undump(new ByteArrayInputStream(lua_binary_file_bytes), "main.lua");
+ * LuaClosure c = new LuaClosure(p, globals);
+ * c.call();
+ * } </pre>
+ * 
+ * 
+ * More commonly, the {@link Globals#undumper} may be used to undump them:
+ * <pre> {@code
+ * Prototype p = globals.loadPrototype(new ByteArrayInputStream(lua_binary_file_bytes), "main.lua", "b");
+ * LuaClosure c = new LuaClosure(p, globals);
+ * c.call();
+ * } </pre>
+ * 
+ * @see luac
+ * @see LoadState
+ * @see Globals
+ * @see Prototype
+ */
 public class DumpState {
 
 	/** set true to allow integer compilation */

src/core/org/luaj/vm2/compiler/LuaC.java

@@ -39,25 +39,36 @@ import org.luaj.vm2.lib.BaseLib;
 
 /**
  * Compiler for Lua.
+ * 
  * <p>
  * 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.  
+ * 
  * <p>
  * Implements the {@link Globals.Compiler} interface for loading 
  * initialized chunks, which is an interface common to 
  * lua bytecode compiling and java bytecode compiling.
+ *  
  * <p> 
- * 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:
  * <pre> {@code
- * LuaValue _G = JsePlatform.standardGlobals();
+ * Globals globals = JsePlatform.standardGlobals();
- * LoadState.load( new ByteArrayInputStream("print 'hello'".getBytes()), "main.lua", _G ).call();
+ * globals.load(new StringReader("print 'hello'"), "main.lua" ).call();
  * } </pre>
- * @see LuaCompiler
+ * 
+ * To load the LuaC compiler manually, use the install method:
+ * <pre> {@code
+ * LuaC.install(globals);
+ * } </pre>
+ * 
+ * @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) {
+	public static void install(Globals globals) {
-		g.compiler = instance;
+		globals.compiler = instance;
-		g.loader = instance;
+		globals.loader = instance;
 	}
 
 	protected static void _assert(boolean 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. 
  * <p>
  * Typically, this library is included as part of a call to either 
+ * {@link JsePlatform#standardGlobals()} or
  * {@link JmePlatform#standardGlobals()}
- * <p>
- * To instantiate and use it directly, 
- * link it into your globals table via {@link LuaValue#load(LuaValue)} using code such as:
  * <pre> {@code
- * LuaTable _G = new LuaTable();
+ * Globals globals = JsePlatform.standardGlobals();
- * LuaThread.setGlobals(_G);
+ * globals.get("print").call(LuaValue.valueOf("hello, world"));
- * _G.load(new BaseLib());
+ * } </pre>
- * _G.get("print").call(LuaValue.valueOf("hello, world"));
+ * <p>
+ * 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:
+ * <pre> {@code
+ * Globals globals = new Globals();
+ * globals.load(new JseBaseLib());
+ * globals.get("print").call(LuaValue.valueOf("hello, world"));
  * } </pre>
  * 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 <a href="http://www.lua.org/manual/5.1/manual.html#5.1">http://www.lua.org/manual/5.1/manual.html#5.1</a>
+ * @see <a href="http://www.lua.org/manual/5.2/manual.html#6.1">Lua 5.2 Base Lib Reference</a>
  */
 public class BaseLib extends TwoArgFunction implements ResourceFinder {
 	

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.
+ * <p> 
+ * Typically, this library is included as part of a call to either 
+ * {@link JsePlatform#standardGlobals()} or {@link JmePlatform#standardGlobals()}
+ * <pre> {@code
+ * Globals globals = JsePlatform.standardGlobals();
+ * System.out.println( globals.get("bit32").get("bnot").call( LuaValue.valueOf(2) ) );
+ * } </pre>
+ * <p>
+ * To instantiate and use it directly, 
+ * link it into your globals table via {@link LuaValue#load(LuaValue)} using code such as:
+ * <pre> {@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) ) );
+ * } </pre>
+ * <p>
+ * 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 <a href="http://www.lua.org/manual/5.2/manual.html#6.7">Lua 5.2 Bitwise Operation Lib Reference</a>
  */
 public class Bit32Lib extends TwoArgFunction {
 

src/core/org/luaj/vm2/lib/CoroutineLib.java

@@ -40,20 +40,25 @@ import org.luaj.vm2.Varargs;
  * <p> 
  * Typically, this library is included as part of a call to either 
  * {@link JsePlatform#standardGlobals()} or {@link JmePlatform#standardGlobals()}
+ * <pre> {@code
+ * Globals globals = JsePlatform.standardGlobals();
+ * System.out.println( globals.get("coroutine").get("running").call() );
+ * } </pre>
  * <p>
  * To instantiate and use it directly, 
  * link it into your globals table via {@link LuaValue#load(LuaValue)} using code such as:
  * <pre> {@code
- * LuaTable _G = new LuaTable();
+ * Globals globals = new Globals();
- * _G.load(new CoroutineLib());
+ * globals.load(new JseBaseLib());
+ * globals.load(new PackageLib());
+ * globals.load(new CoroutineLib());
+ * System.out.println( globals.get("coroutine").get("running").call() );
  * } </pre>
- * Doing so will ensure the library is properly initialized 
- * and loaded into the globals table. 
  * <p>
  * @see LibFunction
  * @see JsePlatform
  * @see JmePlatform
- * @see <a href="http://www.lua.org/manual/5.1/manual.html#5.2">http://www.lua.org/manual/5.1/manual.html#5.2</a>
+ * @see <a href="http://www.lua.org/manual/5.2/manual.html#6.2">Lua 5.2 Coroutine Lib Reference</a>
  */
 public class CoroutineLib extends TwoArgFunction {
 

src/core/org/luaj/vm2/lib/DebugLib.java

@@ -50,20 +50,25 @@ import org.luaj.vm2.Varargs;
  * <p> 
  * Typically, this library is included as part of a call to either 
  * {@link JsePlatform#debugGlobals()} or {@link JmePlatform#debugGlobals()}
+ * <pre> {@code
+ * Globals globals = JsePlatform.debugGlobals();
+ * System.out.println( globals.get("debug").get("traceback").call() );
+ * } </pre>
  * <p>
  * To instantiate and use it directly, 
  * link it into your globals table via {@link LuaValue#load(LuaValue)} using code such as:
  * <pre> {@code
- * Globals _G = new Globals();
+ * Globals globals = new Globals();
- * _G.load(new DebugLib());
+ * globals.load(new JseBaseLib());
+ * globals.load(new PackageLib());
+ * globals.load(new DebugLib());
+ * System.out.println( globals.get("debug").get("traceback").call() );
  * } </pre>
- * Doing so will ensure the library is properly initialized 
- * and loaded into the globals table. 
  * <p>
  * @see LibFunction
  * @see JsePlatform
  * @see JmePlatform
- * @see <a href="http://www.lua.org/manual/5.1/manual.html#5.9">http://www.lua.org/manual/5.1/manual.html#5.9</a>
+ * @see <a href="http://www.lua.org/manual/5.2/manual.html#6.10">Lua 5.2 Debug Lib Reference</a>
  */
 public class DebugLib extends TwoArgFunction {
 	public static final boolean CALLS = (null != System.getProperty("CALLS"));

src/core/org/luaj/vm2/lib/IoLib.java

@@ -47,20 +47,23 @@ import org.luaj.vm2.Varargs;
  * <p> 
  * Typically, this library is included as part of a call to either 
  * {@link JsePlatform#standardGlobals()} or {@link JmePlatform#standardGlobals()}
+ * <pre> {@code
+ * Globals globals = JsePlatform.standardGlobals();
+ * globals.get("io").get("write").call(LuaValue.valueOf("hello, world\n"));
+ * } </pre>
+ * 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}.
  * <p>
  * To instantiate and use it directly, 
  * link it into your globals table via {@link LuaValue#load(LuaValue)} using code such as:
  * <pre> {@code
- * LuaTable _G = new LuaTable();
+ * Globals globals = new Globals();
- * _G.load(new JseIoLib());
+ * globals.load(new JseBaseLib());
- * LuaThread.setGlobals(_G);
+ * globals.load(new PackageLib());
- * _G.load(new JseBaseLib());
+ * globals.load(new OsLib());
- * _G.load(new PackageLib());
+ * globals.get("io").get("write").call(LuaValue.valueOf("hello, world\n"));
- * _G.load(new JseIoLib());
- * _G.get("io").get("write").call(LuaValue.valueOf("hello, world\n"));
  * } </pre>
- * Doing so will ensure the library is properly initialized 
- * and loaded into the globals table. 
  * <p>
  * This has been implemented to match as closely as possible the behavior in the corresponding library in C.
  * @see LibFunction

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.
  * <p> 
  * Typically, this library is included as part of a call to either 
- * {@link JmePlatform#standardGlobals()}
+ * {@link JsePlatform#standardGlobals()} or {@link JmePlatform#standardGlobals()}
+ * <pre> {@code
+ * Globals globals = JsePlatform.standardGlobals();
+ * System.out.println( globals.get("math").get("sqrt").call( LuaValue.valueOf(2) ) );
+ * } </pre>
+ * When using {@link JsePlaform} as in this example, the subclass {@link JseMathLib} will 
+ * be included, which also includes this base functionality.
  * <p>
  * To instantiate and use it directly, 
  * link it into your globals table via {@link LuaValue#load(LuaValue)} using code such as:
  * <pre> {@code
- * LuaTable _G = new LuaTable();
+ * Globals globals = new Globals();
- * LuaThread.setGlobals(_G);
+ * globals.load(new JseBaseLib());
- * _G.load(new BaseLib());
+ * globals.load(new PackageLib());
- * _G.load(new PackageLib());
+ * globals.load(new MathLib());
- * _G.load(new MathLib());
+ * System.out.println( globals.get("math").get("sqrt").call( LuaValue.valueOf(2) ) );
- * System.out.println( _G.get("math").get("sqrt").call( LuaValue.valueOf(2) ) );
  * } </pre>
  * 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 <a href="http://www.lua.org/manual/5.1/manual.html#5.6">http://www.lua.org/manual/5.1/manual.html#5.6</a>
+ * @see <a href="http://www.lua.org/manual/5.2/manual.html#6.6">Lua 5.2 Math Lib Reference</a>
  */
 public class MathLib extends TwoArgFunction {
 	

src/core/org/luaj/vm2/lib/OsLib.java

@@ -55,20 +55,23 @@ import org.luaj.vm2.Varargs;
  * </ul>
  * <p>
  * Typically, this library is included as part of a call to either 
- * {@link JmePlatform#standardGlobals()}
+ * {@link JsePlatform#standardGlobals()} or {@link JmePlatform#standardGlobals()}
+ * <pre> {@code
+ * Globals globals = JsePlatform.standardGlobals();
+ * System.out.println( globals.get("os").get("time").call() );
+ * } </pre>
+ * In this example the platform-specific {@link JseOsLib} library will be loaded, which will include
+ * the base functionality provided by this class.
  * <p>
  * To instantiate and use it directly, 
  * link it into your globals table via {@link LuaValue#load(LuaValue)} using code such as:
  * <pre> {@code
- * LuaTable _G = new LuaTable();
+ * Globals globals = new Globals();
- * LuaThread.setGlobals(_G);
+ * globals.load(new JseBaseLib());
- * _G.load(new BaseLib());
+ * globals.load(new PackageLib());
- * _G.load(new PackageLib());
+ * globals.load(new OsLib());
- * _G.load(new OsLib());
+ * System.out.println( globals.get("os").get("time").call() );
- * System.out.println( _G.get("os").get("time").call() );
  * } </pre>
- * Doing so will ensure the library is properly initialized 
- * and loaded into the globals table. 
  * <p>
   * @see LibFunction
  * @see JseOsLib

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. 
  * 
- * <p>
+ * <h3>Lua Environment Variables</h3>
+ * The following variables are available to lua scrips when this library has been loaded:
+ * <ul>
+ * <li><code>"package.loaded"</code> Lua table of loaded modules.
+ * <li><code>"package.path"</code> Search path for lua scripts.
+ * <li><code>"package.preload"</code> Lua table of uninitialized preload functions.
+ * <li><code>"package.searchers"</code> Lua table of functions that search for object to load.
+ * </ul>
+ * 
+ * <h3>Java Environment Variables</h3>
+ * These Java environment variables affect the library behavior:
+ * <ul>
+ * <li><code>"luaj.package.path"</code> Initial value for <code>"package.path"</code>.  Default value is <code>"?.lua"</code>
+ * </ul>
+ * 
+ * <h3>Loading</h3>
  * Typically, this library is included as part of a call to either 
  * {@link JsePlatform#standardGlobals()} or {@link JmePlatform#standardGlobals()}
+ * <pre> {@code
+ * Globals globals = JsePlatform.standardGlobals();
+ * System.out.println( globals.get("require").call"foo") );
+ * } </pre>
  * <p>
  * To instantiate and use it directly, 
  * link it into your globals table via {@link LuaValue#load(LuaValue)} using code such as:
  * <pre> {@code
- * Globals _G = new Globals();
+ * Globals globals = new Globals();
- * _G.load(new BaseLib());
+ * globals.load(new JseBaseLib());
- * _G.load(new PackageLib());
+ * globals.load(new PackageLib());
- * System.out.println( _G.package_.require.call"foo") );
+ * System.out.println( globals.get("require").call("foo") );
  * } </pre>
- * In practice, the first 3 lines of the above are minimal requirements to get 
+ * <h3>Limitations</h3>
- * and initialize a globals table capable of basic require, print, and other functions, 
+ * This library has been implemented to match as closely as possible the behavior in the corresponding library in C.
- * so it is much more convenient to use the {@link JsePlatform} and {@link JmePlatform} 
- * utility classes instead.  
- * <p>
- * This 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. 
+ * <p>
  * @see LibFunction
  * @see BaseLib
  * @see JseBaseLib
  * @see JsePlatform
  * @see JmePlatform
- * @see <a href="http://www.lua.org/manual/5.1/manual.html#5.3">http://www.lua.org/manual/5.1/manual.html#5.3</a>
+ * @see <a href="http://www.lua.org/manual/5.2/manual.html#6.3">Lua 5.2 Package Lib Reference</a>
  */
 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. */
+	 * <code>"luaj.package.path"</code>, and is <code>"?.lua"</code> by default. */
 	public static String DEFAULT_LUA_PATH = System.getProperty("luaj.package.path");
 	static {
 		if (DEFAULT_LUA_PATH == null)

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. 
- * 
  * <p>
  * Typically, this library is included as part of a call to either 
  * {@link JsePlatform#standardGlobals()} or {@link JmePlatform#standardGlobals()}
+ * <pre> {@code
+ * Globals globals = JsePlatform.standardGlobals();
+ * System.out.println( globals.get("string").get("upper").call( LuaValue.valueOf("abcde") ) );
+ * } </pre>
  * <p>
  * To instantiate and use it directly, 
  * link it into your globals table via {@link LuaValue#load(LuaValue)} using code such as:
  * <pre> {@code
- * LuaTable _G = new LuaTable();
+ * Globals globals = new Globals();
- * LuaThread.setGlobals(_G);
+ * globals.load(new JseBaseLib());
- * _G.load(new BaseLib());
+ * globals.load(new PackageLib());
- * _G.load(new PackageLib());
+ * globals.load(new StringLib());
- * _G.load(new StringLib());
+ * System.out.println( globals.get("string").get("upper").call( LuaValue.valueOf("abcde") ) );
- * System.out.println( _G.get("string").get("upper").call( LuaValue.valueOf("abcde") ) );
  * } </pre>
- * Doing so will ensure the library is properly initialized 
- * and loaded into the globals table. 
  * <p>
  * This is a direct port of the corresponding library in C.
  * @see LibFunction
  * @see JsePlatform
  * @see JmePlatform
- * @see <a href="http://www.lua.org/manual/5.1/manual.html#5.4">http://www.lua.org/manual/5.1/manual.html#5.4</a>
+ * @see <a href="http://www.lua.org/manual/5.2/manual.html#6.4">Lua 5.2 String Lib Reference</a>
  */
 public class StringLib extends TwoArgFunction {
 

src/core/org/luaj/vm2/lib/TableLib.java

@@ -32,29 +32,26 @@ import org.luaj.vm2.Varargs;
  * <p>
  * Typically, this library is included as part of a call to either 
  * {@link JsePlatform#standardGlobals()} or {@link JmePlatform#standardGlobals()}
+ * <pre> {@code
+ * Globals globals = JsePlatform.standardGlobals();
+ * System.out.println( globals.get("table").get("length").call( LuaValue.tableOf() ) );
+ * } </pre>
  * <p>
  * To instantiate and use it directly, 
  * link it into your globals table via {@link LuaValue#load(LuaValue)} using code such as:
  * <pre> {@code
- * LuaTable _G = new LuaTable();
+ * Globals globals = new Globals();
- * LuaThread.setGlobals(_G);
+ * globals.load(new JseBaseLib());
- * _G.load(new BaseLib());
+ * globals.load(new PackageLib());
- * _G.load(new PackageLib());
+ * globals.load(new TableLib());
- * _G.load(new TableLib());
+ * System.out.println( globals.get("table").get("length").call( LuaValue.tableOf() ) );
- * 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 ) );
  * } </pre>
- * Doing so will ensure the library is properly initialized 
- * and loaded into the globals table. 
  * <p>
  * 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 <a href="http://www.lua.org/manual/5.1/manual.html#5.5">http://www.lua.org/manual/5.1/manual.html#5.5</a>
+ * @see <a href="http://www.lua.org/manual/5.2/manual.html#6.5">Lua 5.2 Table Lib Reference</a>
  */
 public class TableLib extends TwoArgFunction {
 

src/jme/org/luaj/vm2/lib/jme/JmeIoLib.java

@@ -49,7 +49,7 @@ import org.luaj.vm2.lib.LibFunction;
  * <p>
  * 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:
  * <pre> {@code
  * Globals globals = new Globals();
  * globals.load(new JmeBaseLib());

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();
+			globals = nodebug? JsePlatform.standardGlobals(): JsePlatform.debugGlobals();
-			if ( luajc ) LuaJC.install(_G);
+			if ( luajc ) LuaJC.install(globals);
 			for ( int i=0, n=libs!=null? libs.size(): 0; i<n; i++ )
 				loadLibrary( (String) libs.elementAt(i) );
 			
@@ -181,12 +179,12 @@ public class lua {
 		LuaValue slibname =LuaValue.valueOf(libname); 
 		try {
 			// load via plain require
-			_G.get("require").call(slibname);
+			globals.get("require").call(slibname);
 		} catch ( Exception e ) {
 			try {
 				// load as java class
 				LuaValue v = (LuaValue) Class.forName(libname).newInstance(); 
-				v.call(slibname, _G);
+				v.call(slibname, globals);
 			} catch ( Exception f ) {
 				throw new IOException("loadLibrary("+libname+") failed: "+e+","+f );
 			}
@@ -198,21 +196,21 @@ public class lua {
 			LuaValue c;
 			try {
 				c = encoding != null? 
-						_G.load(new InputStreamReader(script, encoding), chunkname):
+						globals.load(new InputStreamReader(script, encoding), chunkname):
-						_G.load(script, chunkname, "bt", _G);
+						globals.load(script, chunkname, "bt", globals);
 			} finally {
 				script.close();
 			}
 			if (print && c.isclosure())
 				Print.print(c.checkclosure().p);
-			Varargs scriptargs = setGlobalArg(chunkname, args, firstarg, _G);
+			Varargs scriptargs = setGlobalArg(chunkname, args, firstarg, globals);
 			c.invoke( scriptargs );
 		} catch ( Exception e ) {
 			e.printStackTrace( System.err );
 		}
 	}
 
-	private static Varargs setGlobalArg(String chunkname, String[] args, int i, LuaValue _G) {
+	private static Varargs setGlobalArg(String chunkname, String[] args, int i, LuaValue globals) {
 		if (args == null)
 			return LuaValue.NONE;
 		LuaTable arg = LuaValue.tableOf();
@@ -220,7 +218,7 @@ public class lua {
 			arg.set( j-i, LuaValue.valueOf(args[j]) );
 		arg.set(0, LuaValue.valueOf(chunkname));
 		arg.set(-1, LuaValue.valueOf("luaj"));
-		_G.set("arg", arg);
+		globals.set("arg", arg);
 		return arg.unpack();
 	}
 

src/jse/org/luaj/vm2/lib/jse/CoerceJavaToLua.java

@@ -21,14 +21,12 @@
 ******************************************************************************/
 package org.luaj.vm2.lib.jse;
 
-import java.lang.reflect.Array;
 import java.util.HashMap;
 import java.util.Map;
 
 import org.luaj.vm2.LuaDouble;
 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;
 

src/jse/org/luaj/vm2/lib/jse/CoerceLuaToJava.java

@@ -22,18 +22,13 @@
 package org.luaj.vm2.lib.jse;
 
 import java.lang.reflect.Array;
-import java.lang.reflect.Constructor;
-import java.lang.reflect.InvocationTargetException;
-import java.lang.reflect.Method;
 import java.util.Collections;
 import java.util.HashMap;
 import java.util.Map;
 
-import org.luaj.vm2.LuaError;
 import org.luaj.vm2.LuaString;
 import org.luaj.vm2.LuaTable;
 import org.luaj.vm2.LuaValue;
-import org.luaj.vm2.Varargs;
 
 /**
  * Helper class to coerce values from lua to Java within the luajava library. 

src/jse/org/luaj/vm2/lib/jse/JavaClass.java

@@ -33,7 +33,6 @@ import java.util.List;
 import java.util.Map;
 import java.util.Map.Entry;
 
-import org.luaj.vm2.LuaError;
 import org.luaj.vm2.LuaValue;
 
 /**

src/jse/org/luaj/vm2/lib/jse/JseIoLib.java

@@ -50,7 +50,7 @@ import org.luaj.vm2.lib.LibFunction;
  * <p>
  * 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:
  * <pre> {@code
  * Globals globals = new Globals();
  * globals.load(new JseBaseLib());

src/jse/org/luaj/vm2/lib/jse/JseMathLib.java

@@ -35,18 +35,18 @@ import org.luaj.vm2.lib.LibFunction;
  * {@link JsePlatform#standardGlobals()}
  * <pre> {@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) ) );
  * } </pre>
  * <p>
  * 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:
  * <pre> {@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) ) );
  * } </pre>
  * <p>However, other libraries such as <em>CoroutineLib</em> are not loaded in this case.
  * <p>

src/jse/org/luaj/vm2/lib/jse/JseOsLib.java

@@ -48,18 +48,18 @@ import org.luaj.vm2.lib.LibFunction;
  * {@link JsePlatform#standardGlobals()}
  * <pre> {@code
  * Globals globals = JsePlatform.standardGlobals();
- * System.out.println( _G.get("os").get("time").call() );
+ * System.out.println( globals.get("os").get("time").call() );
  * } </pre>
  * <p>
  * 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:
  * <pre> {@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() );
  * } </pre>
  * <p>However, other libraries such as <em>MathLib</em> are not loaded in this case.
  * <p>

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 
  * <a href="http://www.keplerproject.org/luajava/">luajava</a> documentation pages.
+ * 
  * <p>
- * 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()}
+ * <pre> {@code
+ * Globals globals = JsePlatform.standardGlobals();
+ * System.out.println( globals.get("luajava").get("bindClass").call( LuaValue.valueOf("java.lang.System") ).invokeMethod("currentTimeMillis") );
+ * } </pre>
  * <p>
  * 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:
  * <pre> {@code
- * LuaTable _G = new LuaTable();
+ * Globals globals = new Globals();
- * LuaThread.setGlobals(_G);
+ * globals.load(new JseBaseLib());
- * LuaC.install();
+ * globals.load(new PackageLib());
- * _G.load(new BaseLib());
+ * globals.load(new LuajavaLib());
- * _G.load(new PackageLib());
+ * globals.load( 
- * _G.load(new LuajavaLib());
- * _G.get("load").call( LuaValue.valueOf( 
  *      "sys = luajava.bindClass('java.lang.System')\n"+
- * 		"print ( sys:currentTimeMillis() )\n" ) ).call(); 
+ *      "print ( sys:currentTimeMillis() )\n", "main.lua" ).call(); 
  * } </pre>
- * This example is not intended to be realistic - only to show how the {@link LuajavaLib} 
+ * <p>
- * 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.  
+ * Because it makes extensive use of Java's reflection API, it is not available 
+ * on JME, but can be used in Android applications.
  * <p>
  * 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 <a href="http://www.keplerproject.org/luajava/manual.html#luareference">http://www.keplerproject.org/luajava/manual.html#luareference</a>
  */
 public class LuajavaLib extends VarArgFunction {

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. 
  * <p>
+ * 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}. 
+ * <p>
+ * To override the default compiling behavior with {@link LuaJC}
+ * lua-to-java bytecode compiler, install it before undumping code, 
+ * for example:
+ * <pre> {@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();
+ * } </pre>
+ * <p>
  * 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.  
- * <p>
+ * 
- * 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:
- * <pre> {@code
- * LuaValue _G = JsePlatform.standardGlobals();
- * LuaJC.install(_G);
- * _G.loadString("print 'hello'").call();
- * } </pre>
  * @see LuaCompiler
  * @see LuaC
  * @see BaseLib

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;

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 );

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);
+				LuaJC.install(globals);
-				f = _G.loadfile(filename).arg1();
+				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);
+		InputStream is = globals.FINDER.findResource(filename);
-		Hashtable t = LuaJC.instance.compileAll(is, filename, filename, _G, true);
+		Hashtable t = LuaJC.instance.compileAll(is, filename, filename, globals, true);
 
         // write out the chunk
     	for ( Enumeration e = t.keys(); e.hasMoreElements(); ) {

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);
+					LuaJC.install(globals);
-					chunk = _G.load(reader, name);
+					chunk = globals.load(reader, name);
 					break;
 				default:
-					Prototype p = _G.compilePrototype(reader, name);
+					Prototype p = globals.compilePrototype(reader, name);
-					chunk = new LuaClosure(p, _G);
+					chunk = new LuaClosure(p, globals);
 					Print.print(p);
 					break;
 				}

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() );

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);
+					LuaJC.install(globals);
-					return _G.load(script, name, "bt", _G);
+					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();

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) {

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 );

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 );

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();

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 );