Update javadoc comments related to library inintialization.

This commit is contained in:
James Roseborough
2013-11-22 17:13:55 +00:00
parent 2123d3f924
commit 04fd646c87
14 changed files with 186 additions and 140 deletions

View File

@@ -3,7 +3,15 @@ import org.luaj.vm2.Globals;
import org.luaj.vm2.LuaValue;
import org.luaj.vm2.lib.jse.JsePlatform;
/** Simple program showing the minimal Java program to launch a script. */
/** Simple program showing the minimal Java program to launch a script.
*
* <p> In typical usage, a Globals object must be created to hold global state,
* and it can be used to compile and load lua files into executable LuaValue
* instances.
*
* @see Globals
* @see LuaValue
*/
public class SampleJseMain {
public static void main(String[] args) throws Exception {
@@ -12,7 +20,7 @@ public class SampleJseMain {
// create an environment to run in
Globals globals = JsePlatform.standardGlobals();
// Use the convenience function on the globals to load a chunk.
// Use the convenience function on Globals to load a chunk.
LuaValue chunk = globals.loadfile(script);
// Use any of the "call()" or "invoke()" functions directly on the chunk.

View File

@@ -5,11 +5,12 @@ import org.luaj.vm2.lib.jse.JsePlatform;
/** Simple toy program illustrating how to run Luaj in multiple threads.
*
* By creating separate Globals in each thread, scripts can be run in each thread.
* <p>By creating separate Globals in each thread, scripts can be run in each thread.
*
* However note the following:
* - type-related metatables such as LuaNumber.s_metatable are shared by all threads, so are not thread-safe.
* - creating additional threads within a Java element called by lua could result in shared access to globals.
* <p>However note the following:
* <ul><li>type-related metatables such as LuaNumber.s_metatable are shared by all threads, so are not thread-safe.
* </li><li>creating additional threads within a Java element called by lua could result in shared access to globals.
* </li></ul>
*/
public class SampleMultiThreaded {

View File

@@ -1,8 +1,3 @@
/**
* Sample luaj program that uses the LuaParser class for parsing, and intercepts the
* generated ParseExceptions and fills in the file, line and column information where
* the exception occurred.
*/
import java.io.*;
import org.luaj.vm2.ast.*;
@@ -11,7 +6,13 @@ import org.luaj.vm2.ast.Stat.FuncDef;
import org.luaj.vm2.ast.Stat.LocalFuncDef;
import org.luaj.vm2.parser.*;
/**
* Sample luaj program that uses the LuaParser class for parsing, and intercepts the
* generated ParseExceptions and fills in the file, line and column information where
* the exception occurred.
*
* @see LuaParser
*/
public class SampleParser {
static public void main(String[] args) {

View File

@@ -1,5 +1,3 @@
import java.io.CharArrayReader;
import java.io.CharArrayWriter;
import java.io.Reader;
@@ -16,22 +14,42 @@ import javax.script.SimpleBindings;
import org.luaj.vm2.LuaValue;
import org.luaj.vm2.lib.OneArgFunction;
/** Sample code that uses the JSE-223 pluggable scripting language interface
* to instantiate and use luaj.
*
* <p>In this case, Globals are only indirectly constructed as a side effect
* of using the scripting interface.
*
* <p>All features should be supported including compiled scripts.
*
* <p>Configuration is via system properties:
* <ul><li><b>"org.luaj.luajc"</b> - set to "true" to use the LuaJC lua-to-Java-bytecode compiling.
* Requires the bcel library to be on the class path.
* </li><li><b>"org.luaj.debug"</b> - set to "true" to load the debug library,
* which may provide better stack traces for closures.
* </li></ul>
*
* <p> These flag values can be set on the command line or via code.
*/
public class ScriptEngineSample {
public static void main(String [] args) {
// Set the property 'luaj.debug' before getting the engine to get
// Set the property 'org.luaj.debug' before getting the engine to get
// the debug libraries, which will be slower, but may provide stack traces
// when luaJC is not used.
// System.setProperty("luaj.debug", "true");
// This can also be set on the command line using -Dorg.luaj.debug=true
// System.setProperty("org.luaj.debug", "true");
// Set the property 'org.luaj.luajc' before getting the engine to enable
// the lua-to-java bytecode compiler, which requires the bcel library
// to be on the class path.
// This can also be set on the command line using -Dorg.luaj.luajc=true
// org.luaj.vm2.luajc.LuaJC.install();
ScriptEngineManager sem = new ScriptEngineManager();
ScriptEngine e = sem.getEngineByName("luaj");
ScriptEngineFactory f = e.getFactory();
// uncomment to enable the lua-to-java bytecode compiler
// (requires bcel library in class path)
// org.luaj.vm2.luajc.LuaJC.install();
System.out.println( "Engine name: " +f.getEngineName() );
System.out.println( "Engine Version: " +f.getEngineVersion() );
System.out.println( "LanguageName: " +f.getLanguageName() );

View File

@@ -35,10 +35,10 @@ import org.luaj.vm2.lib.ResourceFinder;
* Global environment used by luaj.
* <p>
* Contains the global variables referenced by lua libraries such as stdin and stdout,
* the resrouce finder which is used tolook up files in a platform independent way,
* the resource finder which is used to look up files in a platform independent way,
* the installed lua compiler, the math library in use, debugging calls stack, and so on.
* <p>
* In a multithreded server environment, each server thread should create one Globals instance,
* In a multi-threaded server environment, each server thread should create one Globals instance,
* which will be logically distance and not interfere with each other, but share certain
* static immutable resources such as class data and string data.
* <p>
@@ -46,12 +46,12 @@ import org.luaj.vm2.lib.ResourceFinder;
* {@link JsePlatform.standardGlobasl()} or {@link JmePlatform.standardGlobals()},
* and then used to load lua scripts for execution as in the following example.
* <pre> {@code
* Globals _G = JsePlatform.standardGlobals();
* _G.compiler.load( new ByteArrayInputStream("print 'hello'".getBytes()), "main.lua", _G ).call();
* Globals globals = JsePlatform.standardGlobals();
* globals.compiler.load( new ByteArrayInputStream("print 'hello'".getBytes()), "main.lua", _G ).call();
* } </pre>
* @see LuaCompiler
* @see JsePlatform
* @see JmePlatform
* @see org.luaj.vm2.lib.jse.JsePlatform
* @see org.luaj.vm2.lib.jme.JmePlatform
* @see LuaValue
*
*/
@@ -107,13 +107,16 @@ public class Globals extends LuaTable {
return this;
}
/** The installed loader. */
/** The installed loader.
* @see Loader */
public Loader loader;
/** The installed compiler. */
/** The installed compiler.
* @see Compiler */
public Compiler compiler;
/** The installed undumper. */
/** The installed undumper.
* @see Undumper */
public Undumper undumper;
/** Convenience function for loading a file that is either binary lua or lua source.

View File

@@ -22,7 +22,6 @@
package org.luaj.vm2.lib;
import org.luaj.vm2.Globals;
import org.luaj.vm2.LuaError;
import org.luaj.vm2.LuaTable;
import org.luaj.vm2.LuaThread;
import org.luaj.vm2.LuaValue;

View File

@@ -30,7 +30,6 @@ import javax.microedition.io.StreamConnection;
import org.luaj.vm2.LuaString;
import org.luaj.vm2.LuaValue;
import org.luaj.vm2.lib.BaseLib;
import org.luaj.vm2.lib.IoLib;
import org.luaj.vm2.lib.LibFunction;
@@ -43,27 +42,30 @@ import org.luaj.vm2.lib.LibFunction;
* <p>
* Typically, this library is included as part of a call to
* {@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();
* LuaThread.setGlobals(_G);
* _G.load(new BaseLib());
* _G.load(new PackageLib());
* _G.load(new JmeIoLib());
* _G.get("io").get("write").call(LuaValue.valueOf("hello, world\n"));
* Globals globals = JmePlatform.standardGlobals();
* globals.get("io").get("write").call(LuaValue.valueOf("hello, world\n"));
* } </pre>
* Doing so will ensure the library is properly initialized
* and loaded into the globals table.
* <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:
* <pre> {@code
* Globals globals = new Globals();
* globals.load(new JmeBaseLib());
* globals.load(new PackageLib());
* globals.load(new JmeIoLib());
* globals.get("io").get("write").call(LuaValue.valueOf("hello, world\n"));
* } </pre>
* <p>However, other libraries such as <em>MathLib</em> are not loaded in this case.
* <p>
* This has been implemented to match as closely as possible the behavior in the corresponding library in C.
* @see LibFunction
* @see JsePlatform
* @see org.luaj.vm2.lib.jse.JsePlatform
* @see JmePlatform
* @see IoLib
* @see JseIoLib
* @see <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.8">Lua 5.2 I/O Lib Reference</a>
*/
public class JmeIoLib extends IoLib {

View File

@@ -53,18 +53,18 @@ import org.luaj.vm2.lib.TableLib;
* <p>
* A simple example of initializing globals and using them from Java is:
* <pre> {@code
* Globals _G = JmePlatform.standardGlobals();
* _G.get("print").call(LuaValue.valueOf("hello, world"));
* Globals global = JmePlatform.standardGlobals();
* global.get("print").call(LuaValue.valueOf("hello, world"));
* } </pre>
* <p>
* Once globals are created, a simple way to load and run a script is:
* <pre> {@code
* LoadState.load( getClass().getResourceAsStream("main.lua"), "main.lua", _G ).call();
* LoadState.load( getClass().getResourceAsStream("main.lua"), "main.lua", globals ).call();
* } </pre>
* <p>
* although {@code require} could also be used:
* <pre> {@code
* _G.get("require").call(LuaValue.valueOf("main"));
* globals.get("require").call(LuaValue.valueOf("main"));
* } </pre>
* For this to succeed, the file "main.lua" must be a resource in the class path.
* See {@link BaseLib} for details on finding scripts using {@link ResourceFinder}.
@@ -103,19 +103,19 @@ public class JmePlatform {
* @see JmePlatform
*/
public static Globals standardGlobals() {
Globals _G = new Globals();
_G.load(new BaseLib());
_G.load(new PackageLib());
_G.load(new Bit32Lib());
_G.load(new OsLib());
_G.load(new MathLib());
_G.load(new TableLib());
_G.load(new StringLib());
_G.load(new CoroutineLib());
_G.load(new JmeIoLib());
LoadState.install(_G);
LuaC.install(_G);
return _G;
Globals globals = new Globals();
globals.load(new BaseLib());
globals.load(new PackageLib());
globals.load(new Bit32Lib());
globals.load(new OsLib());
globals.load(new MathLib());
globals.load(new TableLib());
globals.load(new StringLib());
globals.load(new CoroutineLib());
globals.load(new JmeIoLib());
LoadState.install(globals);
LuaC.install(globals);
return globals;
}
/** Create standard globals including the {@link debug} library.
@@ -127,8 +127,8 @@ public class JmePlatform {
* @see DebugLib
*/
public static Globals debugGlobals() {
Globals _G = standardGlobals();
_G.load(new DebugLib());
return _G;
Globals globals = standardGlobals();
globals.load(new DebugLib());
return globals;
}
}

View File

@@ -43,26 +43,30 @@ import org.luaj.vm2.lib.ResourceFinder;
* <p>
* Typically, this library is included as part of a call to
* {@link JsePlatform#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();
* LuaThread.setGlobals(_G);
* _G.load(new JseBaseLib());
* _G.get("print").call(LuaValue.valueOf("hello, world"));
* Globals globals = JsePlatform.standardGlobals();
* globals.get("print").call(LuaValue.valueOf("hello, world"));
* } </pre>
* Doing so will ensure the library is properly initialized
* and loaded into the globals table.
* <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>
* <p>However, other libraries such as <em>PackageLib</em> are not loaded in this case.
* <p>
* This is a direct port of the corresponding library in C.
* @see Globals
* @see BaseLib
* @see ResourceFinder
* @see #FINDER
* @see {@link Globals.FINDER}
* @see LibFunction
* @see JsePlatform
* @see JmePlatform
* @see <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 org.luaj.vm2.lib.jme.JmePlatform
* @see <a href="http://www.lua.org/manual/5.2/manual.html#6.1">Lua 5.2 Base Lib Reference</a>
*/
public class JseBaseLib extends org.luaj.vm2.lib.BaseLib {

View File

@@ -21,7 +21,6 @@
******************************************************************************/
package org.luaj.vm2.lib.jse;
import java.io.BufferedInputStream;
import java.io.EOFException;
import java.io.IOException;
@@ -33,7 +32,6 @@ import java.io.RandomAccessFile;
import org.luaj.vm2.LuaError;
import org.luaj.vm2.LuaString;
import org.luaj.vm2.LuaValue;
import org.luaj.vm2.lib.BaseLib;
import org.luaj.vm2.lib.IoLib;
import org.luaj.vm2.lib.LibFunction;
@@ -45,27 +43,30 @@ import org.luaj.vm2.lib.LibFunction;
* <p>
* Typically, this library is included as part of a call to
* {@link JsePlatform#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();
* LuaThread.setGlobals(_G);
* _G.load(new JseBaseLib());
* _G.load(new PackageLib());
* _G.load(new JseIoLib());
* _G.get("io").get("write").call(LuaValue.valueOf("hello, world\n"));
* Globals globals = JsePlatform.standardGlobals();
* globals.get("io").get("write").call(LuaValue.valueOf("hello, world\n"));
* } </pre>
* Doing so will ensure the library is properly initialized
* and loaded into the globals table.
* <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:
* <pre> {@code
* Globals globals = new Globals();
* globals.load(new JseBaseLib());
* globals.load(new PackageLib());
* globals.load(new JseIoLib());
* globals.get("io").get("write").call(LuaValue.valueOf("hello, world\n"));
* } </pre>
* <p>However, other libraries such as <em>MathLib</em> are not loaded in this case.
* <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 org.luaj.vm2.lib.jme.JmePlatform
* @see IoLib
* @see JmeIoLib
* @see <a href="http://www.lua.org/manual/5.1/manual.html#5.7">http://www.lua.org/manual/5.1/manual.html#5.7</a>
* @see <a href="http://www.lua.org/manual/5.2/manual.html#6.8">Lua 5.2 I/O Lib Reference</a>
*/
public class JseIoLib extends IoLib {

View File

@@ -33,26 +33,29 @@ import org.luaj.vm2.lib.LibFunction;
* <p>
* Typically, this library is included as part of a call to
* {@link JsePlatform#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();
* LuaThread.setGlobals(_G);
* _G.load(new JseBaseLib());
* _G.load(new PackageLib());
* _G.load(new JseMathLib());
* Globals globals = JsePlatform.standardGlobals();
* System.out.println( _G.get("math").get("sqrt").call( LuaValue.valueOf(2) ) );
* } </pre>
* Doing so will ensure the library is properly initialized
* and loaded into the globals table.
* <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:
* <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) ) );
* } </pre>
* <p>However, other libraries such as <em>CoroutineLib</em> are not loaded in this case.
* <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 org.luaj.vm2.lib.jme.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 JseMathLib extends org.luaj.vm2.lib.MathLib {

View File

@@ -20,6 +20,7 @@
* THE SOFTWARE.
******************************************************************************/
package org.luaj.vm2.lib.jse;
import java.io.File;
import java.io.IOException;
@@ -43,27 +44,30 @@ import org.luaj.vm2.lib.LibFunction;
* os-specific features, the behavior of these functions varies considerably
* from their counterparts in the C platform.
* <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()}
* <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();
* LuaThread.setGlobals(_G);
* _G.load(new JseBaseLib());
* _G.load(new PackageLib());
* _G.load(new JseOsLib());
* Globals globals = JsePlatform.standardGlobals();
* System.out.println( _G.get("os").get("time").call() );
* } </pre>
* Doing so will ensure the library is properly initialized
* and loaded into the globals table.
* <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:
* <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() );
* } </pre>
* <p>However, other libraries such as <em>MathLib</em> are not loaded in this case.
* <p>
* @see LibFunction
* @see OsLib
* @see JsePlatform
* @see JmePlatform
* @see <a href="http://www.lua.org/manual/5.1/manual.html#5.8">http://www.lua.org/manual/5.1/manual.html#5.8</a>
* @see org.luaj.vm2.lib.jme.JmePlatform
* @see <a href="http://www.lua.org/manual/5.2/manual.html#6.9">Lua 5.2 OS Lib Reference</a>
*/
public class JseOsLib extends org.luaj.vm2.lib.OsLib {

View File

@@ -42,18 +42,18 @@ import org.luaj.vm2.lib.TableLib;
* <p>
* A simple example of initializing globals and using them from Java is:
* <pre> {@code
* Globals _G = JsePlatform.standardGlobals();
* _G.get("print").call(LuaValue.valueOf("hello, world"));
* Globals globals = JsePlatform.standardGlobals();
* globals.get("print").call(LuaValue.valueOf("hello, world"));
* } </pre>
* <p>
* Once globals are created, a simple way to load and run a script is:
* <pre> {@code
* _G.load( new FileInputStream("main.lua"), "main.lua" ).call();
* globals.load( new FileInputStream("main.lua"), "main.lua" ).call();
* } </pre>
* <p>
* although {@code require} could also be used:
* <pre> {@code
* _G.get("require").call(LuaValue.valueOf("main"));
* globals.get("require").call(LuaValue.valueOf("main"));
* } </pre>
* For this to succeed, the file "main.lua" must be in the current directory or a resource.
* See {@link JseBaseLib} for details on finding scripts using {@link ResourceFinder}.
@@ -91,20 +91,20 @@ public class JsePlatform {
* @see JmePlatform
*/
public static Globals standardGlobals() {
Globals _G = new Globals();
_G.load(new JseBaseLib());
_G.load(new PackageLib());
_G.load(new Bit32Lib());
_G.load(new TableLib());
_G.load(new StringLib());
_G.load(new CoroutineLib());
_G.load(new JseMathLib());
_G.load(new JseIoLib());
_G.load(new JseOsLib());
_G.load(new LuajavaLib());
LoadState.install(_G);
LuaC.install(_G);
return _G;
Globals globals = new Globals();
globals.load(new JseBaseLib());
globals.load(new PackageLib());
globals.load(new Bit32Lib());
globals.load(new TableLib());
globals.load(new StringLib());
globals.load(new CoroutineLib());
globals.load(new JseMathLib());
globals.load(new JseIoLib());
globals.load(new JseOsLib());
globals.load(new LuajavaLib());
LoadState.install(globals);
LuaC.install(globals);
return globals;
}
/** Create standard globals including the {@link debug} library.
@@ -116,9 +116,9 @@ public class JsePlatform {
* @see DebugLib
*/
public static Globals debugGlobals() {
Globals _G = standardGlobals();
_G.load(new DebugLib());
return _G;
Globals globals = standardGlobals();
globals.load(new DebugLib());
return globals;
}

View File

@@ -95,11 +95,13 @@ public class ScriptEngineTests extends TestSuite {
}
public static class LuaJCBindingsTest extends EngineTestCase {
static {
System.setProperty("org.luaj.luajc", "true");
}
protected Bindings createBindings() {
return new SimpleBindings();
}
public void setUp() {
System.setProperty("org.luaj.luajc", "true");
super.setUp();
}
public void testCompiledFunctionIsNotClosure() throws ScriptException {