+* 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. +*
+* A simple pattern for loading and executing code is +*
{@code
+* LuaValue _G = JsePlatform.standardGlobals();
+* LoadState.load( new FileInputStream("main.lua"), "main.lua", _G ).call();
+* }
+* This should work regardless of which {@link LuaCompiler}
+* 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 override the default compiler with, say, the {@link LuaJC} +* lua-to-java bytecode compiler, install it before loading, +* for example: +*
{@code
+* LuaValue _G = JsePlatform.standardGlobals();
+* LuaJC.install();
+* LoadState.load( new FileInputStream("main.lua"), "main.lua", _G ).call();
+* }
+*
* @see LuaCompiler
* @see LuaClosure
* @see LuaFunction
* @see LoadState#compiler
* @see LoadState#load(InputStream, String, LuaValue)
+* @see LuaC
+* @see LuaJC
*/
public class LoadState {
diff --git a/src/core/org/luaj/vm2/LuaFunction.java b/src/core/org/luaj/vm2/LuaFunction.java
index 4bface62..5a4f1146 100644
--- a/src/core/org/luaj/vm2/LuaFunction.java
+++ b/src/core/org/luaj/vm2/LuaFunction.java
@@ -28,6 +28,9 @@ package org.luaj.vm2;
* all built-in library functions coded in Java,
* and {@link LuaClosure}, which represents a lua closure
* whose bytecode is interpreted when the function is invoked.
+ * @see LuaValue
+ * @see LibFunction
+ * @see LuaClosure
*/
abstract
public class LuaFunction extends LuaValue {
diff --git a/src/core/org/luaj/vm2/LuaNil.java b/src/core/org/luaj/vm2/LuaNil.java
index f492ebdf..a3960bc6 100644
--- a/src/core/org/luaj/vm2/LuaNil.java
+++ b/src/core/org/luaj/vm2/LuaNil.java
@@ -34,7 +34,8 @@ package org.luaj.vm2;
* the recommended approach is to use the method {@link LuaValue#isnil()}
* instead. By using that any ambiguities between
* {@link LuaValue#NIL} and {@link LuaValue#NONE} are avoided.
- *
+ * @see LuaValue
+ * @see LuaValue#NIL
*/
public class LuaNil extends LuaValue {
diff --git a/src/core/org/luaj/vm2/LuaNumber.java b/src/core/org/luaj/vm2/LuaNumber.java
index ffc170cd..ef972218 100644
--- a/src/core/org/luaj/vm2/LuaNumber.java
+++ b/src/core/org/luaj/vm2/LuaNumber.java
@@ -28,6 +28,7 @@ package org.luaj.vm2;
* and {@link LuaDouble} which holds all other number values.
* @see LuaInteger
* @see LuaDouble
+ * @see LuaValue
*
*/
abstract
diff --git a/src/core/org/luaj/vm2/LuaTable.java b/src/core/org/luaj/vm2/LuaTable.java
index c52c60ed..a9fcc832 100644
--- a/src/core/org/luaj/vm2/LuaTable.java
+++ b/src/core/org/luaj/vm2/LuaTable.java
@@ -60,11 +60,14 @@ import java.util.Vector;
* + * A LuaThread is typically created in response to a scripted call to + * {@code coroutine.create()} + *
+ * The threads must be initialized with the globals, so that + * the global environment may be passed along according to rules of lua. + * This is done via a call to {@link #setGlobals(LuaValue)} + * at some point during globals initialization. + * See {@link BaseLib} for additional documentation and example code. + *
+ * The utility classes {@link JsePlatform} and {@link JmePlatform} + * see to it that this initialization is done properly. + * For this reason it is highly recommended to use one of these classes + * when initializing globals. + *
+ * The behavior of coroutine threads matches closely the behavior + * of C coroutine library. However, because of the use of Java threads + * to manage call state, it is possible to yield from anywhere in luaj. + * On the other hand, if a {@link LuaThread} is created, then yields + * without ever entering a completed state, then the garbage collector + * may not be able to determine that the thread needs to be collected, + * and this could cause a memory and resource leak. It is recommended + * that all coroutines that are created are resumed until they are in + * a completed state. + * + * @see LuaValue + * @see JsePlatform + * @see JmePlatform + * @see CoroutineLib */ public class LuaThread extends LuaValue implements Runnable { @@ -68,6 +96,11 @@ public class LuaThread extends LuaValue implements Runnable { LuaThread() { } + /** + * Create a LuaThread around a function and environment + * @param func The function to execute + * @param env The environment to apply to the thread + */ public LuaThread(LuaValue func, LuaValue env) { this.env = env; this.func = func; @@ -109,37 +142,66 @@ public class LuaThread extends LuaValue implements Runnable { return STATUS_NAMES[status]; } + /** + * Get the currently running thread. + * @return {@link LuaThread} that is currenly running + */ public static LuaThread getRunning() { return running_thread; } + /** + * Test if this is the main thread + * @return true if this is the main thread + */ public static boolean isMainThread(LuaThread r) { return r == mainthread; } - /** Set the globals of the current thread */ + /** + * Set the globals of the current thread. + *
+ * This must be done once before any other code executes. + * @param globals The global variables for the main ghread. + */ public static void setGlobals(LuaValue globals) { running_thread.env = globals; } - /** Get the current thread's environment */ + /** Get the current thread's environment + * @return {@link LuaValue} containing the global variables of the current thread. + */ public static LuaValue getGlobals() { LuaValue e = running_thread.env; return e!=null? e: LuaValue.error("LuaThread.setGlobals() not initialized"); } - + + /** + * Callback used at the beginning of a call + * @param function Function being called + * @see DebugLib + */ public static final void onCall(LuaFunction function) { running_thread.callstack[running_thread.calls++] = function; if (DebugLib.DEBUG_ENABLED) DebugLib.debugOnCall(running_thread, running_thread.calls, function); } + /** + * Callback used at the end of a call + * @see DebugLib + */ public static final void onReturn() { running_thread.callstack[--running_thread.calls] = null; if (DebugLib.DEBUG_ENABLED) DebugLib.debugOnReturn(running_thread, running_thread.calls); } + /** + * Get number of calls in stack + * @return number of calls in current call stack + * @see DebugLib + */ public static int getCallstackDepth() { return running_thread.calls; } @@ -170,6 +232,11 @@ public class LuaThread extends LuaValue implements Runnable { } } + /** Yield this thread with arguments + * + * @param args The arguments to send as return values to {@link #resume(Varargs)} + * @return {@link Varargs} provided as arguments to {@link #resume(Varargs)} + */ public Varargs yield(Varargs args) { synchronized ( this ) { if ( status != STATUS_RUNNING ) @@ -189,7 +256,11 @@ public class LuaThread extends LuaValue implements Runnable { } } - /** Start or resume this thread */ + /** Start or resume this thread + * + * @param args The arguments to send as return values to {@link #yield(Varargs)} + * @return {@link Varargs} provided as arguments to {@link #yield(Varargs)} + */ public Varargs resume(Varargs args) { synchronized ( this ) { diff --git a/src/core/org/luaj/vm2/LuaValue.java b/src/core/org/luaj/vm2/LuaValue.java index ec3fe779..9ddb3084 100644 --- a/src/core/org/luaj/vm2/LuaValue.java +++ b/src/core/org/luaj/vm2/LuaValue.java @@ -29,22 +29,12 @@ package org.luaj.vm2; * This allows Java clients to deal essentially with one type for all Java values, namely {@link LuaValue}. *
* Constructors are provided as static methods for common Java types, such as - * {@link LuaValue#valueOf(int)} or {@link LuaValue#valueOf(String)}. - * Primarily this is used to encourage instance pooling for small integers or short strings. + * {@link LuaValue#valueOf(int)} or {@link LuaValue#valueOf(String)} + * to allow for instance pooling. *
* Constants are defined for the lua values - * {@link LuaValue#NIL}, {@link LuaValue#TRUE}, and {@link LuaValue#FALSE}. - * A constant {@link LuaValue#NONE} is defined which is a {@link Varargs} list having no values. - * Predefined constants exist for the standard lua type constants - * {@link TNIL}, {@link TBOOLEAN}, {@link TLIGHTUSERDATA}, {@link TNUMBER}, {@link TSTRING}, - * {@link TTABLE}, {@link TFUNCTION}, {@link TUSERDATA}, {@link TTHREAD}, - * extended lua type constants - * {@link TINT}, {@link TNONE}, {@link TVALUE}, - * as well as for the metatags - * {@link INDEX}, {@link NEWINDEX}, {@link CALL}, {@link MODE}, {@link METATABLE}, - * {@link ADD}, {@link SUB}, {@link DIV}, {@link MUL}, {@link POW}, - * {@link MOD}, {@link UNM}, {@link LEN}, {@link EQ}, {@link LT}, - * {@link LE}, {@link TOSTRING}, {@link CONCAT} as well as + * {@link #NIL}, {@link #TRUE}, and {@link #FALSE}. + * A constant {@link #NONE} is defined which is a {@link Varargs} list having no values. *
* Operations are performed on values directly via their Java methods. * For example, the following code divides two numbers: @@ -75,16 +65,47 @@ package org.luaj.vm2; * print.call( r.arg(1), r.arg(2) ); * } *
+ * To load and run a script, {@link LoadState} is used: + *
{@code
+ * LoadState.load( new FileInputStream("main.lua"), "main.lua", globals ).call();
+ * }
+ * + * although {@code require} could also be used: + *
{@code
+ * globals.get("require").call(LuaValue.valueOf("main"));
+ * }
+ * For this to work the file must be in the current directory, or in the class path,
+ * dependening on the platform.
+ * See {@link JsePlatform} and {@link JmePlatform} for details.
+ * * In general a {@link LuaError} may be thrown on any operation when the * types supplied to any operation are illegal from a lua perspective. * Examples could be attempting to concatenate a NIL value, or attempting arithmetic * on values that are not number. *
- * When a {@link LuaTable} is required by an api, a table constructor such as {@link tableOf()} - * can be used, or the type may be coerced via {@link checktable()} or {@link opttable(LuaValue)}. - * Constructors exist to create pre-initialized tables such as {@link LuaValue#tableOf(LuaValue[])} - * for lists, {@link LuaValue#tableOf(LuaValue[], LuaValue[])} for hashtables, - * or {@link LuaValue#tableOf(LuaValue[], LuaValue[], Varargs)} for mixed tables. + * There are several methods for preinitializing tables, such as: + *
+ * Predefined constants exist for the standard lua type constants + * {@link TNIL}, {@link TBOOLEAN}, {@link TLIGHTUSERDATA}, {@link TNUMBER}, {@link TSTRING}, + * {@link TTABLE}, {@link TFUNCTION}, {@link TUSERDATA}, {@link TTHREAD}, + * and extended lua type constants + * {@link TINT}, {@link TNONE}, {@link TVALUE} + *
+ * Predefined constants exist for all strings used as metatags: + * {@link INDEX}, {@link NEWINDEX}, {@link CALL}, {@link MODE}, {@link METATABLE}, + * {@link ADD}, {@link SUB}, {@link DIV}, {@link MUL}, {@link POW}, + * {@link MOD}, {@link UNM}, {@link LEN}, {@link EQ}, {@link LT}, + * {@link LE}, {@link TOSTRING}, and {@link CONCAT}. + * + * @see JsePlatform + * @see JmePlatform + * @see LoadState + * @see Varargs */ abstract public class LuaValue extends Varargs { diff --git a/src/core/org/luaj/vm2/Varargs.java b/src/core/org/luaj/vm2/Varargs.java index cdaa61bf..340bdd20 100644 --- a/src/core/org/luaj/vm2/Varargs.java +++ b/src/core/org/luaj/vm2/Varargs.java @@ -37,13 +37,13 @@ package org.luaj.vm2; * such as {@code LuaValue.varargsOf(LuaValue,Varargs)} * or by taking a portion of the args using {@code Varargs.subargs(int start)} *
- * @see org.luaj.vm2.LuaValue#varargsOf(LuaValue[]) - * @see org.luaj.vm2.LuaValue#varargsOf(LuaValue, Varargs) - * @see org.luaj.vm2.LuaValue#varargsOf(LuaValue[], Varargs) - * @see org.luaj.vm2.LuaValue#varargsOf(LuaValue, LuaValue, Varargs) - * @see org.luaj.vm2.LuaValue#varargsOf(LuaValue[], int, int) - * @see org.luaj.vm2.LuaValue#varargsOf(LuaValue[], int, int, Varargs) - * @see org.luaj.vm2.LuaValue#subargs(int) + * @see LuaValue#varargsOf(LuaValue[]) + * @see LuaValue#varargsOf(LuaValue, Varargs) + * @see LuaValue#varargsOf(LuaValue[], Varargs) + * @see LuaValue#varargsOf(LuaValue, LuaValue, Varargs) + * @see LuaValue#varargsOf(LuaValue[], int, int) + * @see LuaValue#varargsOf(LuaValue[], int, int, Varargs) + * @see LuaValue#subargs(int) */ public abstract class Varargs { diff --git a/src/core/org/luaj/vm2/compiler/LuaC.java b/src/core/org/luaj/vm2/compiler/LuaC.java index 9a32818f..f5bb61bf 100644 --- a/src/core/org/luaj/vm2/compiler/LuaC.java +++ b/src/core/org/luaj/vm2/compiler/LuaC.java @@ -36,7 +36,6 @@ import org.luaj.vm2.LuaValue; import org.luaj.vm2.Prototype; import org.luaj.vm2.LoadState.LuaCompiler; - /** * Compiler for Lua. *
@@ -49,6 +48,20 @@ import org.luaj.vm2.LoadState.LuaCompiler; * initialized chunks, which is an interface common to * lua bytecode compiling and java bytecode compiling. *
+ * Teh {@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();
+ * }
+ * @see LuaCompiler
+ * @see LuaJC
+ * @see JsePlatform
+ * @see JmePlatform
+ * @see BaseLib
+ * @see LuaValue
* @see LuaCompiler
* @see Prototype
*/
diff --git a/src/core/org/luaj/vm2/lib/BaseLib.java b/src/core/org/luaj/vm2/lib/BaseLib.java
index cc08a2e9..aa9f7d16 100644
--- a/src/core/org/luaj/vm2/lib/BaseLib.java
+++ b/src/core/org/luaj/vm2/lib/BaseLib.java
@@ -33,19 +33,41 @@ import org.luaj.vm2.LuaValue;
import org.luaj.vm2.Varargs;
/**
- * Base library implementation, targeted for JME platforms.
- *
- * BaseLib instances are typically used as the initial globals table
- * when creating a new uniqued runtime context.
- *
- * Since JME has no file system by default, dofile and loadfile use the
- * FINDER instance to find resource files. The default loader chain
- * in PackageLib will use these as well.
- *
- * For an implementation that looks in the current directory on JSE,
- * use org.luaj.lib.j2se.BaseLib instead.
- *
- * @see org.luaj.vm2.lib.jse.JseBaseLib
+ * Subclass of {@link LibFunction} which implements the lua basic library functions.
+ * + * This contains all library functions listed as "basic functions" in the lua documentation for JME. + * The functions dofile and loadfile use the + * {@link #FINDER} instance to find resource files. + * Since JME has no file system by default, {@link BaseLib} implements + * {@link ResourceFinder} using {@link Class#getResource(String)}, + * which is the closest equivalent on JME. + * The default loader chain in {@link PackageLib} will use these as well. + *
+ * To use basic library functions that include a {@link ResourceFinder} based on + * directory lookup, use {@link JseBaseLib} instead. + *
+ * Typically, this library is included as part of a call to either + * {@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"));
+ * }
+ * 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 JseBaseLib + * @see ResourceFinder + * @see #FINDER + * @see LibFunction + * @see JsePlatform + * @see JmePlatform + * @see http://www.lua.org/manual/5.1/manual.html#5.1 */ public class BaseLib extends OneArgFunction implements ResourceFinder { public static final String VERSION = "Luaj 2.0"; diff --git a/src/core/org/luaj/vm2/lib/CoroutineLib.java b/src/core/org/luaj/vm2/lib/CoroutineLib.java index e63853dd..428ba7fd 100644 --- a/src/core/org/luaj/vm2/lib/CoroutineLib.java +++ b/src/core/org/luaj/vm2/lib/CoroutineLib.java @@ -1,5 +1,5 @@ /******************************************************************************* -* Copyright (c) 2007 LuaJ. All rights reserved. +* Copyright (c) 2007-2011 LuaJ. All rights reserved. * * Permission is hereby granted, free of charge, to any person obtaining a copy * of this software and associated documentation files (the "Software"), to deal @@ -26,6 +26,34 @@ import org.luaj.vm2.LuaThread; import org.luaj.vm2.LuaValue; import org.luaj.vm2.Varargs; +/** + * Subclass of {@link LibFunction} which implements the lua standard {@code coroutine} + * library. + *
+ * The coroutine library in luaj has the same behavior as the + * coroutine library in C, but is implemented using Java Threads to maintain + * the call state between invocations. Therefore it can be yielded from anywhere, + * similar to the "Coco" yield-from-anywhere patch available for C-based lua. + * However, coroutines that are yielded but never resumed to complete their execution + * may not be collected by the garbage collector. + *
+ * 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();
+ * _G.load(new CoroutineLib());
+ * }
+ * 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 + */ public class CoroutineLib extends VarArgFunction { private static final int INIT = 0; diff --git a/src/core/org/luaj/vm2/lib/DebugLib.java b/src/core/org/luaj/vm2/lib/DebugLib.java index 0cd9b359..281438e5 100644 --- a/src/core/org/luaj/vm2/lib/DebugLib.java +++ b/src/core/org/luaj/vm2/lib/DebugLib.java @@ -1,5 +1,5 @@ /******************************************************************************* -* Copyright (c) 2009 Luaj.org. All rights reserved. +* Copyright (c) 2009-2011 Luaj.org. All rights reserved. * * Permission is hereby granted, free of charge, to any person obtaining a copy * of this software and associated documentation files (the "Software"), to deal @@ -36,6 +36,34 @@ import org.luaj.vm2.Print; import org.luaj.vm2.Prototype; import org.luaj.vm2.Varargs; +/** + * Subclass of {@link LibFunction} which implements the lua standard {@code debug} + * library. + *
+ * The debug library in luaj tries to emulate the behavior of the corresponding C-based lua library. + * To do this, it must maintain a separate stack of calls to {@link LuaClosure} and {@link LibFunction} + * instances. + * Especially when lua-to-java bytecode compiling is being used + * via a {@link LuaCompiler} such as {@link LuaJC}, + * this cannot be done in all cases. + *
+ * Typically, this library is included as part of a call to either + * {@link JsePlatform#debugGlobals()} or {@link JmePlatform#debugGlobals()} + *
+ * 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 DebugLib());
+ * }
+ * 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 + */ public class DebugLib extends VarArgFunction { public static final boolean CALLS = (null != System.getProperty("CALLS")); public static final boolean TRACE = (null != System.getProperty("TRACE")); diff --git a/src/core/org/luaj/vm2/lib/IoLib.java b/src/core/org/luaj/vm2/lib/IoLib.java index 45b1042c..429caefe 100644 --- a/src/core/org/luaj/vm2/lib/IoLib.java +++ b/src/core/org/luaj/vm2/lib/IoLib.java @@ -1,5 +1,5 @@ /******************************************************************************* -* Copyright (c) 2009 Luaj.org. All rights reserved. +* Copyright (c) 2009-2011 Luaj.org. All rights reserved. * * Permission is hereby granted, free of charge, to any person obtaining a copy * of this software and associated documentation files (the "Software"), to deal @@ -30,8 +30,45 @@ import org.luaj.vm2.LuaTable; import org.luaj.vm2.LuaValue; import org.luaj.vm2.Varargs; - - +/** + * Abstract base class extending {@link LibFunction} which implements the + * core of the lua standard {@code io} library. + *
+ * It contains the implementation of the io library support that is common to + * the JSE and JME platforms. + * In practice on of the concrete IOLib subclasses is chosen: + * {@link org.luaj.vm2.lib.jse.JseIoLib} for the JSE platform, and + * {@link org.luaj.vm2.lib.jme.JmeIoLib} for the JME platform. + *
+ * The JSE implementation conforms almost completely to the C-based lua library, + * while the JME implementation follows closely except in the area of random-access files, + * which are difficult to support properly on JME. + *
+ * 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();
+ * _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"));
+ * }
+ * 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 JseIoLib + * @see JmeIoLib + * @see http://www.lua.org/manual/5.1/manual.html#5.7 + */ abstract public class IoLib extends OneArgFunction { diff --git a/src/core/org/luaj/vm2/lib/LibFunction.java b/src/core/org/luaj/vm2/lib/LibFunction.java index ca129338..bed23e7e 100644 --- a/src/core/org/luaj/vm2/lib/LibFunction.java +++ b/src/core/org/luaj/vm2/lib/LibFunction.java @@ -1,5 +1,5 @@ /******************************************************************************* -* Copyright (c) 2009 Luaj.org. All rights reserved. +* Copyright (c) 2009-2011 Luaj.org. All rights reserved. * * Permission is hereby granted, free of charge, to any person obtaining a copy * of this software and associated documentation files (the "Software"), to deal @@ -25,11 +25,112 @@ import org.luaj.vm2.LuaError; import org.luaj.vm2.LuaFunction; import org.luaj.vm2.LuaValue; +/** + * Subclass of {@link LuaFunction} common to Java functions exposed to lua. + *
+ * To provide for common implementations in JME and JSE, + * library functions are typically grouped on one or more library classes + * and an opcode per library function is defined and used to key the switch + * to the correct function within the library. + *
+ * Since lua functions can be called with too few or too many arguments, + * and there are overloaded {@link LuaValue#call()} functions with varying + * number of arguments, a Java function exposed in lua needs to handle the + * argument fixup when a function is called with a number of arguments + * differs from that expected. + *
+ * To simplify the creation of library functions, + * there are 5 direct subclasses to handle common cases based on number of + * argument values and number of return return values. + *
+ * To be a Java library that can be loaded via {@code require}, it should have + * a public constructor that returns a {@link LuaValue} that, when executed, + * initializes the library. + *
+ * For example, the following code will implement a library called "hyperbolic" + * with two functions, "sinh", and "cosh": + *
{@code
+ * import org.luaj.vm2.LuaValue;
+ * public class hyperbolic extends org.luaj.vm2.lib.OneArgFunction {
+ * public hyperbolic() {}
+ * public LuaValue call(LuaValue arg) {
+ * switch ( opcode ) {
+ * case 0: {
+ * LuaValue t = tableOf();
+ * this.bind(t, hyperbolic.class, new String[] { "sinh", "cosh" }, 1 );
+ * env.set("hyperbolic", t);
+ * return t;
+ * }
+ * case 1: return valueOf(Math.sinh(arg.todouble()));
+ * case 2: return valueOf(Math.cosh(arg.todouble()));
+ * default: return error("bad opcode: "+opcode);
+ * }
+ * }
+ * }
+ * }
+ * The default constructor is both to instantiate the library
+ * in response to {@code require 'hyperbolic'} statement,
+ * provided it is on Javas class path,
+ * and to instantiate copies of the {@code hyperbolic}
+ * class when initializing library instances. .
+ * The instance returned by the default constructor will be invoked
+ * as part of library loading.
+ * In response, it creates two more instances, one for each library function,
+ * in the body of the {@code switch} statement {@code case 0}
+ * via the {@link #bind(LuaValue, Class, String[], int)} utility method.
+ * It also registers the table in the globals via the {@link #env}
+ * local variable, which should be the global environment unless
+ * it has been changed.
+ * {@code case 1} and {@code case 2} will be called when {@code hyperbolic.sinh}
+ * {@code hyperbolic.sinh} and {@code hyperbolic.cosh} are invoked.
+ * + * To test it, a script such as this can be used: + *
{@code
+ * local t = require('hyperbolic')
+ * print( 't', t )
+ * print( 'hyperbolic', hyperbolic )
+ * for k,v in pairs(t) do
+ * print( 'k,v', k,v )
+ * end
+ * print( 'sinh(.5)', hyperbolic.sinh(.5) )
+ * print( 'cosh(.5)', hyperbolic.cosh(.5) )
+ * }
+ * + * It should produce something like: + *
{@code
+ * t table: 3dbbd23f
+ * hyperbolic table: 3dbbd23f
+ * k,v cosh cosh
+ * k,v sinh sinh
+ * sinh(.5) 0.5210953
+ * cosh(.5) 1.127626
+ * }
+ * + * See the source code in any of the library functions + * such as {@link BaseLib} or {@link TableLib} for specific examples. + */ abstract public class LibFunction extends LuaFunction { + /** User-defined opcode to differentiate between instances of the library function class. + *
+ * Subclass will typicall switch on this value to provide the specific behavior for each function. + */ protected int opcode; + + /** The common name for this function, useful for debugging. + *
+ * Binding functions initialize this to the name to which it is bound. + */ protected String name; + /** Default constructor for use by subclasses */ protected LibFunction() { } @@ -37,10 +138,31 @@ abstract public class LibFunction extends LuaFunction { return name != null? name: super.tojstring(); } + /** + * Bind a set of library functions. + *
+ * An array of names is provided, and the first name is bound + * with opcode = 0, second with 1, etc. + * @param env The environment to apply to each bound function + * @param factory the Class to instantiate for each bound function + * @param names array of String names, one for each function. + * @see #bind(LuaValue, Class, String[], int) + */ protected void bind(LuaValue env, Class factory, String[] names ) { bind( env, factory, names, 0 ); } + /** + * Bind a set of library functions, with an offset + *
+ * An array of names is provided, and the first name is bound
+ * with opcode = {@code firstopcode}, second with {@code firstopcode+1}, etc.
+ * @param env The environment to apply to each bound function
+ * @param factory the Class to instantiate for each bound function
+ * @param names array of String names, one for each function.
+ * @param firstopcode the first opcode to use
+ * @see #bind(LuaValue, Class, String[])
+ */
protected void bind(LuaValue env, Class factory, String[] names, int firstopcode ) {
try {
for ( int i=0, n=names.length; i
+ * The implementations of {@code exp()} and {@code pow()} are constructed by
+ * 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()}
+ *
+ * To instantiate and use it directly,
+ * link it into your globals table via {@link LuaValue#load(LuaValue)} using code such as:
+ *
+ * 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 JseMathLib
+ * @see http://www.lua.org/manual/5.1/manual.html#5.6
*/
public class MathLib extends OneArgFunction {
diff --git a/src/core/org/luaj/vm2/lib/OneArgFunction.java b/src/core/org/luaj/vm2/lib/OneArgFunction.java
index e9707d66..9c99d30d 100644
--- a/src/core/org/luaj/vm2/lib/OneArgFunction.java
+++ b/src/core/org/luaj/vm2/lib/OneArgFunction.java
@@ -1,5 +1,5 @@
/*******************************************************************************
-* Copyright (c) 2009 Luaj.org. All rights reserved.
+* Copyright (c) 2009-2011 Luaj.org. All rights reserved.
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
@@ -24,13 +24,39 @@ package org.luaj.vm2.lib;
import org.luaj.vm2.LuaValue;
import org.luaj.vm2.Varargs;
+/** Abstract base class for Java function implementations that take one argument and
+ * return one value.
+ *
+ * Subclasses need only implement {@link LuaValue#call(LuaValue)} to complete this class,
+ * simplifying development.
+ * All other uses of {@link #call()}, {@link #invoke(Varargs)},etc,
+ * are routed through this method by this class,
+ * dropping or extending arguments with {@code nil} values as required.
+ *
+ * If more than one argument are required, or no arguments are required,
+ * or variable argument or variable return values,
+ * then use one of the related function
+ * {@link ZeroArgFunction}, {@link TwoArgFunction}, {@link ThreeArgFunction}, or {@link VarArgFunction}.
+ *
+ * See {@link LibFunction} for more information on implementation libraries and library functions.
+ * @see #call(LuaValue)
+ * @see LibFunction
+ * @see ZeroArgFunction
+ * @see TwoArgFunction
+ * @see ThreeArgFunction
+ * @see VarArgFunction
+ */
abstract public class OneArgFunction extends LibFunction {
abstract public LuaValue call(LuaValue arg);
+ /** Default constructor */
public OneArgFunction() {
}
+ /** Constructor with specific environment
+ * @param env The environment to apply during constructon.
+ */
public OneArgFunction( LuaValue env ) {
this.env = env;
}
diff --git a/src/core/org/luaj/vm2/lib/OsLib.java b/src/core/org/luaj/vm2/lib/OsLib.java
index aaa6d229..de3da2c5 100644
--- a/src/core/org/luaj/vm2/lib/OsLib.java
+++ b/src/core/org/luaj/vm2/lib/OsLib.java
@@ -28,23 +28,49 @@ import org.luaj.vm2.LuaValue;
import org.luaj.vm2.Varargs;
/**
- * Base implementation of OsLib, with simplified stub functions
+ * Subclass of {@link LibFunction} which implements the standard lua {@code os} library.
+ *
+ * It is a usable base with simplified stub functions
* for library functions that cannot be implemented uniformly
* on Jse and Jme.
- *
*
* This can be installed as-is on either platform, or extended
* and refined to be used in a complete Jse implementation.
- *
- * Contains limited implementations of features not supported well on Jme:
- *
+ * Because the nature of the {@code os} library is to encapsulate
+ * os-specific features, the behavior of these functions varies considerably
+ * from their counterparts in the C platform.
+ *
+ * The following functions have limited implementations of features
+ * that are not supported well on Jme:
+ *
+ * Typically, this library is included as part of a call to either
+ * {@link JmePlatform#standardGlobals()}
+ *
+ * To instantiate and use it directly,
+ * link it into your globals table via {@link LuaValue#load(LuaValue)} using code such as:
+ *
+ * @see LibFunction
+ * @see JseOsLib
+ * @see JsePlatform
+ * @see JmePlatform
+ * @see http://www.lua.org/manual/5.1/manual.html#5.8
*/
public class OsLib extends VarArgFunction {
public static String TMP_PREFIX = ".luaj";
diff --git a/src/core/org/luaj/vm2/lib/PackageLib.java b/src/core/org/luaj/vm2/lib/PackageLib.java
index 32dd9f12..15a6be81 100644
--- a/src/core/org/luaj/vm2/lib/PackageLib.java
+++ b/src/core/org/luaj/vm2/lib/PackageLib.java
@@ -1,5 +1,5 @@
/*******************************************************************************
-* Copyright (c) 2010 Luaj.org. All rights reserved.
+* Copyright (c) 2010-2011 Luaj.org. All rights reserved.
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
@@ -31,7 +31,38 @@ import org.luaj.vm2.LuaThread;
import org.luaj.vm2.LuaValue;
import org.luaj.vm2.Varargs;
-
+/**
+ * Subclass of {@link LibFunction} which implements the lua standard package and module
+ * library functions.
+ *
+ *
+ * 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:
+ *
+ * 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} documetnation.
+ * @see LibFunction
+ * @see BaseLib
+ * @see JseBaseLib
+ * @see JsePlatform
+ * @see JmePlatform
+ * @see http://www.lua.org/manual/5.1/manual.html#5.3
+ */
public class PackageLib extends OneArgFunction {
public static String DEFAULT_LUA_PATH = "?.lua";
diff --git a/src/core/org/luaj/vm2/lib/ResourceFinder.java b/src/core/org/luaj/vm2/lib/ResourceFinder.java
index 72d6cb57..218fa8e4 100644
--- a/src/core/org/luaj/vm2/lib/ResourceFinder.java
+++ b/src/core/org/luaj/vm2/lib/ResourceFinder.java
@@ -1,5 +1,5 @@
/*******************************************************************************
- * Copyright (c) 2009 Luaj.org. All rights reserved.
+ * Copyright (c) 2009-2011 Luaj.org. All rights reserved.
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
@@ -25,15 +25,22 @@ import java.io.InputStream;
/**
* Interface for opening application resource files such as scripts sources.
- *
+ *
* This is used by required to load files that are part of
* the application, and implemented by BaseLib
* for both the Jme and Jse platforms.
- *
- * The Jme version implements FileOpener via getResourceAsStream(),
- * while the Jse version implements it using new File().
- *
- * The io library does not use this API for file manipulation.
+ *
+ * The Jme version of base lib {@link BaseLib}
+ * implements {@link BaseLib#FINDER} via {@link Class#getResourceAsStream(String)},
+ * while the Jse version {@link JseBaseLib} implements it using {@link java.io.File#File(String)}.
+ *
+ * The io library does not use this API for file manipulation.
+ *
+ * @see BaseLib
+ * @see BaseLib#FINDER
+ * @see JseBaseLib
+ * @see JmePlatform
+ * @see JsePlatform
*/
public interface ResourceFinder {
diff --git a/src/core/org/luaj/vm2/lib/StringLib.java b/src/core/org/luaj/vm2/lib/StringLib.java
index 4ebe4c43..0c9d47e3 100644
--- a/src/core/org/luaj/vm2/lib/StringLib.java
+++ b/src/core/org/luaj/vm2/lib/StringLib.java
@@ -1,5 +1,5 @@
/*******************************************************************************
-* Copyright (c) 2009 Luaj.org. All rights reserved.
+* Copyright (c) 2009-2011 Luaj.org. All rights reserved.
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
@@ -32,6 +32,33 @@ import org.luaj.vm2.LuaValue;
import org.luaj.vm2.Varargs;
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()}
+ *
+ * To instantiate and use it directly,
+ * link it into your globals table via {@link LuaValue#load(LuaValue)} using code such as:
+ *
+ * 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
+ */
public class StringLib extends OneArgFunction {
public static LuaTable instance;
diff --git a/src/core/org/luaj/vm2/lib/TableLib.java b/src/core/org/luaj/vm2/lib/TableLib.java
index cfa2dcd4..6fd3b394 100644
--- a/src/core/org/luaj/vm2/lib/TableLib.java
+++ b/src/core/org/luaj/vm2/lib/TableLib.java
@@ -25,6 +25,37 @@ import org.luaj.vm2.LuaTable;
import org.luaj.vm2.LuaValue;
import org.luaj.vm2.Varargs;
+/**
+ * Subclass of {@link LibFunction} which implements the lua standard {@code table}
+ * library.
+ *
+ *
+ * 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:
+ *
+ * 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
+ */
public class TableLib extends OneArgFunction {
public TableLib() {
diff --git a/src/core/org/luaj/vm2/lib/ThreeArgFunction.java b/src/core/org/luaj/vm2/lib/ThreeArgFunction.java
index 35db1a0b..d958d726 100644
--- a/src/core/org/luaj/vm2/lib/ThreeArgFunction.java
+++ b/src/core/org/luaj/vm2/lib/ThreeArgFunction.java
@@ -24,13 +24,39 @@ package org.luaj.vm2.lib;
import org.luaj.vm2.LuaValue;
import org.luaj.vm2.Varargs;
+/** Abstract base class for Java function implementations that take two arguments and
+ * return one value.
+ *
+ * Subclasses need only implement {@link LuaValue#call(LuaValue,LuaValue,LuaValue)} to complete this class,
+ * simplifying development.
+ * All other uses of {@link #call()}, {@link #invoke(Varargs)},etc,
+ * are routed through this method by this class,
+ * dropping or extending arguments with {@code nil} values as required.
+ *
+ * If more or less than three arguments are required,
+ * or variable argument or variable return values,
+ * then use one of the related function
+ * {@link ZeroArgFunction}, {@link OneArgFunction}, {@link TwoArgFunction}, or {@link VarArgFunction}.
+ *
+ * See {@link LibFunction} for more information on implementation libraries and library functions.
+ * @see #call(LuaValue,LuaValue,LuaValue)
+ * @see LibFunction
+ * @see ZeroArgFunction
+ * @see OneArgFunction
+ * @see TwoArgFunction
+ * @see VarArgFunction
+ */
abstract public class ThreeArgFunction extends LibFunction {
abstract public LuaValue call(LuaValue arg1, LuaValue arg2, LuaValue arg3);
+ /** Default constructor */
public ThreeArgFunction() {
}
+ /** Constructor with specific environment
+ * @param env The environment to apply during constructon.
+ */
public ThreeArgFunction( LuaValue env ) {
this.env = env;
}
diff --git a/src/core/org/luaj/vm2/lib/TwoArgFunction.java b/src/core/org/luaj/vm2/lib/TwoArgFunction.java
index 67dab83a..b2c1b0c7 100644
--- a/src/core/org/luaj/vm2/lib/TwoArgFunction.java
+++ b/src/core/org/luaj/vm2/lib/TwoArgFunction.java
@@ -24,13 +24,39 @@ package org.luaj.vm2.lib;
import org.luaj.vm2.LuaValue;
import org.luaj.vm2.Varargs;
+/** Abstract base class for Java function implementations that take two arguments and
+ * return one value.
+ *
+ * Subclasses need only implement {@link LuaValue#call(LuaValue,LuaValue)} to complete this class,
+ * simplifying development.
+ * All other uses of {@link #call()}, {@link #invoke(Varargs)},etc,
+ * are routed through this method by this class,
+ * dropping or extending arguments with {@code nil} values as required.
+ *
+ * If more or less than two arguments are required,
+ * or variable argument or variable return values,
+ * then use one of the related function
+ * {@link ZeroArgFunction}, {@link OneArgFunction}, {@link ThreeArgFunction}, or {@link VarArgFunction}.
+ *
+ * See {@link LibFunction} for more information on implementation libraries and library functions.
+ * @see #call(LuaValue,LuaValue)
+ * @see LibFunction
+ * @see ZeroArgFunction
+ * @see OneArgFunction
+ * @see ThreeArgFunction
+ * @see VarArgFunction
+ */
abstract public class TwoArgFunction extends LibFunction {
abstract public LuaValue call(LuaValue arg1, LuaValue arg2);
+ /** Default constructor */
public TwoArgFunction() {
}
+ /** Constructor with specific environment
+ * @param env The environment to apply during constructon.
+ */
public TwoArgFunction( LuaValue env ) {
this.env = env;
}
diff --git a/src/core/org/luaj/vm2/lib/VarArgFunction.java b/src/core/org/luaj/vm2/lib/VarArgFunction.java
index 561a4b75..7888f724 100644
--- a/src/core/org/luaj/vm2/lib/VarArgFunction.java
+++ b/src/core/org/luaj/vm2/lib/VarArgFunction.java
@@ -25,6 +25,27 @@ import org.luaj.vm2.LuaThread;
import org.luaj.vm2.LuaValue;
import org.luaj.vm2.Varargs;
+/** Abstract base class for Java function implementations that takes varaiable arguments and
+ * returns multiple return values.
+ *
+ * Subclasses need only implement {@link LuaValue#invoke(Varargs)} to complete this class,
+ * simplifying development.
+ * All other uses of {@link #call(LuaValue)}, {@link #invoke()},etc,
+ * are routed through this method by this class,
+ * converting arguments to {@linnk Varargs} and
+ * dropping or extending return values with {@code nil} values as required.
+ *
+ * If between one and three arguments are required, and only one return value is returned,
+ * {@link ZeroArgFunction}, {@link OneArgFunction}, {@link TwoArgFunction}, or {@link ThreeArgFunction}.
+ *
+ * See {@link LibFunction} for more information on implementation libraries and library functions.
+ * @see #invoke(Varargs)
+ * @see LibFunction
+ * @see ZeroArgFunction
+ * @see OneArgFunction
+ * @see TwoArgFunction
+ * @see ThreeArgFunction
+ */
abstract public class VarArgFunction extends LibFunction {
public VarArgFunction() {
}
diff --git a/src/core/org/luaj/vm2/lib/ZeroArgFunction.java b/src/core/org/luaj/vm2/lib/ZeroArgFunction.java
index 0ed9ec90..526d2fed 100644
--- a/src/core/org/luaj/vm2/lib/ZeroArgFunction.java
+++ b/src/core/org/luaj/vm2/lib/ZeroArgFunction.java
@@ -1,5 +1,5 @@
/*******************************************************************************
-* Copyright (c) 2009 Luaj.org. All rights reserved.
+* Copyright (c) 2009-2011 Luaj.org. All rights reserved.
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
@@ -24,13 +24,37 @@ package org.luaj.vm2.lib;
import org.luaj.vm2.LuaValue;
import org.luaj.vm2.Varargs;
+/** Abstract base class for Java function implementations that take no arguments and
+ * return one value.
+ *
+ * Subclasses need only implement {@link LuaValue#call()} to complete this class,
+ * simplifying development.
+ * All other uses of {@link #call(LuaValue)}, {@link #invoke(Varargs)},etc,
+ * are routed through this method by this class.
+ *
+ * If one or more arguments are required, or variable argument or variable return values,
+ * then use one of the related function
+ * {@link OneArgFunction}, {@link TwoArgFunction}, {@link ThreeArgFunction}, or {@link VarArgFunction}.
+ *
+ * See {@link LibFunction} for more information on implementation libraries and library functions.
+ * @see #call()
+ * @see LibFunction
+ * @see OneArgFunction
+ * @see TwoArgFunction
+ * @see ThreeArgFunction
+ * @see VarArgFunction
+ */
abstract public class ZeroArgFunction extends LibFunction {
abstract public LuaValue call();
+ /** Default constructor */
public ZeroArgFunction() {
}
+ /** Constructor with specific environment
+ * @param env The environment to apply during constructon.
+ */
public ZeroArgFunction( LuaValue env ) {
this.env = env;
}
diff --git a/src/jme/org/luaj/vm2/lib/jme/JmeIoLib.java b/src/jme/org/luaj/vm2/lib/jme/JmeIoLib.java
index 813b1f15..1a66df9e 100644
--- a/src/jme/org/luaj/vm2/lib/jme/JmeIoLib.java
+++ b/src/jme/org/luaj/vm2/lib/jme/JmeIoLib.java
@@ -1,5 +1,5 @@
/*******************************************************************************
-* Copyright (c) 2009 Luaj.org. All rights reserved.
+* Copyright (c) 2009-2011 Luaj.org. All rights reserved.
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
@@ -29,13 +29,41 @@ import javax.microedition.io.Connector;
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;
-/**
- * Implementation of the lua io library based on CLDC 1.0 and StreamConnection.
- *
- * Seek is not supported.
+/**
+ * Subclass of {@link IoLib} and therefore {@link LibFunction} which implements the lua standard {@code io}
+ * library for the JSE platform.
+ *
+ * The implementation of the is based on CLDC 1.0 and StreamConnection.
+ * However, seek is not supported.
+ *
+ * Typically, this library is included as part of a call to
+ * {@link JmePlatform#standardGlobals()}
+ *
+ * To instantiate and use it directly,
+ * link it into your globals table via {@link LuaValue#load(LuaValue)} using code such as:
+ *
+ * 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 IoLib
+ * @see JseIoLib
+ * @see http://www.lua.org/manual/5.1/manual.html#5.6
*/
public class JmeIoLib extends IoLib {
diff --git a/src/jme/org/luaj/vm2/lib/jme/JmePlatform.java b/src/jme/org/luaj/vm2/lib/jme/JmePlatform.java
index fbd648ae..04e6482a 100644
--- a/src/jme/org/luaj/vm2/lib/jme/JmePlatform.java
+++ b/src/jme/org/luaj/vm2/lib/jme/JmePlatform.java
@@ -22,8 +22,10 @@
package org.luaj.vm2.lib.jme;
import org.luaj.vm2.compiler.LuaC;
+import org.luaj.vm2.LoadState;
import org.luaj.vm2.LuaTable;
import org.luaj.vm2.LuaThread;
+import org.luaj.vm2.LuaValue;
import org.luaj.vm2.lib.BaseLib;
import org.luaj.vm2.lib.CoroutineLib;
import org.luaj.vm2.lib.DebugLib;
@@ -33,12 +35,69 @@ import org.luaj.vm2.lib.PackageLib;
import org.luaj.vm2.lib.StringLib;
import org.luaj.vm2.lib.TableLib;
+/** The {@link JmePlatform} class is a convenience class to standardize
+ * how globals tables are initialized for the JME platform.
+ *
+ * The JME platform, being limited, cannot implement all libraries in all aspects. The main limitations are
+ *
+ * It is used to allocate either a set of standard globals using
+ * {@link #standardGlobals()} or debug globals using {@link #debugGlobals()}
+ *
+ * A simple example of initializing globals and using them from Java is:
+ *
+ * Once globals are created, a simple way to load and run a script is:
+ *
+ * although {@code require} could also be used:
+ *
+ * The standard globals will contain all standard libraries in their JME flavors:
+ *
+ * The debug globals are simply the standard globals plus the {@code debug} library {@link DebugLib}.
+ *
+ *
+ * The class ensures that initialization is done in the correct order,
+ * and that linkage is made to {@link LuaThread#setGlobals(LuaValue)}.
+ * @see JsePlatform
+ * @see LoadState
+ */
public class JmePlatform {
/**
* Create a standard set of globals for JME including all the libraries.
*
* @return Table of globals initialized with the standard JME libraries
+ * @see #debugGlobals()
+ * @see JsePlatform
+ * @see JmePlatform
*/
public static LuaTable standardGlobals() {
LuaTable _G = new LuaTable();
@@ -55,6 +114,14 @@ public class JmePlatform {
return _G;
}
+ /** Create standard globals including the {@link debug} library.
+ *
+ * @return Table of globals initialized with the standard JSE and debug libraries
+ * @see #standarsGlobals()
+ * @see JsePlatform
+ * @see JmePlatform
+ * @see DebugLib
+ */
public static LuaTable debugGlobals() {
LuaTable _G = standardGlobals();
_G.load(new DebugLib());
diff --git a/src/jse/org/luaj/vm2/lib/jse/CoerceJavaToLua.java b/src/jse/org/luaj/vm2/lib/jse/CoerceJavaToLua.java
index 48655618..75be82fa 100644
--- a/src/jse/org/luaj/vm2/lib/jse/CoerceJavaToLua.java
+++ b/src/jse/org/luaj/vm2/lib/jse/CoerceJavaToLua.java
@@ -1,5 +1,5 @@
/*******************************************************************************
-* Copyright (c) 2009 Luaj.org. All rights reserved.
+* Copyright (c) 2009-2011 Luaj.org. All rights reserved.
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
@@ -29,7 +29,11 @@ import org.luaj.vm2.LuaInteger;
import org.luaj.vm2.LuaString;
import org.luaj.vm2.LuaValue;
-
+/**
+ * Helper class to coerce values from Java to lua within the luajava library.
+ *
+ * @see LuajavaLib
+ */
public class CoerceJavaToLua {
public static interface Coercion {
diff --git a/src/jse/org/luaj/vm2/lib/jse/CoerceLuaToJava.java b/src/jse/org/luaj/vm2/lib/jse/CoerceLuaToJava.java
index 04714b4a..cea1ab29 100644
--- a/src/jse/org/luaj/vm2/lib/jse/CoerceLuaToJava.java
+++ b/src/jse/org/luaj/vm2/lib/jse/CoerceLuaToJava.java
@@ -1,5 +1,5 @@
/*******************************************************************************
-* Copyright (c) 2009 Luaj.org. All rights reserved.
+* Copyright (c) 2009-2011 Luaj.org. All rights reserved.
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
@@ -29,7 +29,11 @@ import org.luaj.vm2.LuaError;
import org.luaj.vm2.LuaValue;
import org.luaj.vm2.Varargs;
-
+/**
+ * Helper class to coerce values from lua to Java within the luajava library.
+ *
+ * @see LuajavaLib
+ */
public class CoerceLuaToJava {
public static interface Coercion {
diff --git a/src/jse/org/luaj/vm2/lib/jse/JseBaseLib.java b/src/jse/org/luaj/vm2/lib/jse/JseBaseLib.java
index 3636ec79..1bcd1e81 100644
--- a/src/jse/org/luaj/vm2/lib/jse/JseBaseLib.java
+++ b/src/jse/org/luaj/vm2/lib/jse/JseBaseLib.java
@@ -26,16 +26,45 @@ import java.io.FileInputStream;
import java.io.IOException;
import java.io.InputStream;
+import org.luaj.vm2.LuaValue;
+import org.luaj.vm2.lib.BaseLib;
+import org.luaj.vm2.lib.LibFunction;
+import org.luaj.vm2.lib.ResourceFinder;
/**
- * Base library implementation, targeted for JSE platforms.
- *
- * Implements the same library functions as org.luaj.lib.BaseLib,
- * but looks in the current directory for files loaded via
- * loadfile(), dofile() and require().
- *
- * @see org.luaj.vm2.lib.jse.JseBaseLib
+ * Subclass of {@link BaseLib} and {@link LibFunction} which implements the lua basic library functions
+ * and provides a directory based {@link ResourceFinder} as the {@link #FINDER}.
+ *
+ * Since JME has no file system by default, {@link BaseLib} implements
+ * {@link ResourceFinder} using {@link Class#getResource(String)}.
+ * The {@link JseBaseLib} implements {@link FINDER} by scanning the current directory
+ * first, then falling back to {@link Class#getResource(String)} if that fails.
+ * Otherwise, the behavior is the same as that of {@link BaseLib}.
+ *
+ * Typically, this library is included as part of a call to
+ * {@link JsePlatform#standardGlobals()}
+ *
+ * To instantiate and use it directly,
+ * link it into your globals table via {@link LuaValue#load(LuaValue)} using code such as:
+ *
+ * This is a direct port of the corresponding library in C.
+ * @see BaseLib
+ * @see ResourceFinder
+ * @see #FINDER
+ * @see LibFunction
+ * @see JsePlatform
+ * @see JmePlatform
+ * @see http://www.lua.org/manual/5.1/manual.html#5.1
*/
+
public class JseBaseLib extends org.luaj.vm2.lib.BaseLib {
/** Construct a JSE base library instance */
diff --git a/src/jse/org/luaj/vm2/lib/jse/JseIoLib.java b/src/jse/org/luaj/vm2/lib/jse/JseIoLib.java
index c293a666..8a86ca8f 100644
--- a/src/jse/org/luaj/vm2/lib/jse/JseIoLib.java
+++ b/src/jse/org/luaj/vm2/lib/jse/JseIoLib.java
@@ -30,12 +30,40 @@ 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;
-/**
- * Implementation of the lua io library for J2se using RandomAccessFile
- * to implement seek.
+/**
+ * Subclass of {@link IoLib} and therefore {@link LibFunction} which implements the lua standard {@code io}
+ * library for the JSE platform.
+ *
+ * It uses RandomAccessFile to implement seek on files.
+ *
+ * Typically, this library is included as part of a call to
+ * {@link JsePlatform#standardGlobals()}
+ *
+ * To instantiate and use it directly,
+ * link it into your globals table via {@link LuaValue#load(LuaValue)} using code such as:
+ *
+ * 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 IoLib
+ * @see JmeIoLib
+ * @see http://www.lua.org/manual/5.1/manual.html#5.7
*/
public class JseIoLib extends IoLib {
diff --git a/src/jse/org/luaj/vm2/lib/jse/JseMathLib.java b/src/jse/org/luaj/vm2/lib/jse/JseMathLib.java
index 5bb729c6..1f8d2e69 100644
--- a/src/jse/org/luaj/vm2/lib/jse/JseMathLib.java
+++ b/src/jse/org/luaj/vm2/lib/jse/JseMathLib.java
@@ -1,5 +1,5 @@
/*******************************************************************************
-* Copyright (c) 2009 Luaj.org. All rights reserved.
+* Copyright (c) 2009-2011 Luaj.org. All rights reserved.
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
@@ -22,15 +22,39 @@
package org.luaj.vm2.lib.jse;
import org.luaj.vm2.LuaValue;
-import org.luaj.vm2.lib.MathLib;
+import org.luaj.vm2.lib.LibFunction;
import org.luaj.vm2.lib.OneArgFunction;
import org.luaj.vm2.lib.TwoArgFunction;
-/**
- * Math library implementation for use on JSE platform.
- *
- * Implements all "math" functions, including platform-specific
- * overrides for pow() and exp()
+/**
+ * Subclass of {@link LibFunction} which implements the lua standard {@code math}
+ * library.
+ *
+ * It contains all lua math functions, including those not available on the JME platform.
+ * See {@link org.luaj.lib.MathLib} for the exception list.
+ *
+ * Typically, this library is included as part of a call to
+ * {@link JsePlatform#standardGlobals()}
+ *
+ * To instantiate and use it directly,
+ * link it into your globals table via {@link LuaValue#load(LuaValue)} using code such as:
+ *
+ * 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 JseMathLib
+ * @see http://www.lua.org/manual/5.1/manual.html#5.6
*/
public class JseMathLib extends org.luaj.vm2.lib.MathLib {
diff --git a/src/jse/org/luaj/vm2/lib/jse/JseOsLib.java b/src/jse/org/luaj/vm2/lib/jse/JseOsLib.java
index aba76902..9952cd1c 100644
--- a/src/jse/org/luaj/vm2/lib/jse/JseOsLib.java
+++ b/src/jse/org/luaj/vm2/lib/jse/JseOsLib.java
@@ -23,18 +23,46 @@ package org.luaj.vm2.lib.jse;
import java.io.File;
import java.io.IOException;
+import org.luaj.vm2.LuaValue;
+import org.luaj.vm2.lib.LibFunction;
+
/**
- * Implementation of the lua os library for J2se.
- *
- * Implements features specific to the J2se environment:
- *
+ * This contains more complete implementations of the following functions
+ * using features that are specific to JSE:
+ *
+ * Because the nature of the {@code os} library is to encapsulate
+ * os-specific features, the behavior of these functions varies considerably
+ * from their counterparts in the C platform.
+ *
+ * Typically, this library is included as part of a call to either
+ * {@link JsePlatform#standardGlobals()}
+ *
+ * To instantiate and use it directly,
+ * link it into your globals table via {@link LuaValue#load(LuaValue)} using code such as:
+ *
+ * @see LibFunction
+ * @see OsLib
+ * @see JsePlatform
+ * @see JmePlatform
+ * @see http://www.lua.org/manual/5.1/manual.html#5.8
*/
public class JseOsLib extends org.luaj.vm2.lib.OsLib {
diff --git a/src/jse/org/luaj/vm2/lib/jse/JsePlatform.java b/src/jse/org/luaj/vm2/lib/jse/JsePlatform.java
index 01c0f0ff..7008280e 100644
--- a/src/jse/org/luaj/vm2/lib/jse/JsePlatform.java
+++ b/src/jse/org/luaj/vm2/lib/jse/JsePlatform.java
@@ -1,5 +1,5 @@
/*******************************************************************************
- * Copyright (c) 2009 Luaj.org. All rights reserved.
+ * Copyright (c) 2009-2011 Luaj.org. All rights reserved.
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
@@ -24,18 +24,66 @@ package org.luaj.vm2.lib.jse;
import org.luaj.vm2.compiler.LuaC;
import org.luaj.vm2.LuaTable;
import org.luaj.vm2.LuaThread;
+import org.luaj.vm2.LuaValue;
import org.luaj.vm2.lib.CoroutineLib;
import org.luaj.vm2.lib.DebugLib;
import org.luaj.vm2.lib.PackageLib;
import org.luaj.vm2.lib.StringLib;
import org.luaj.vm2.lib.TableLib;
+/** The {@link JsePlatform} class is a convenience class to standardize
+ * how globals tables are initialized for the JSE platform.
+ *
+ * It is used to allocate either a set of standard globals using
+ * {@link #standardGlobals()} or debug globals using {@link #debugGlobals()}
+ *
+ * A simple example of initializing globals and using them from Java is:
+ *
+ * Once globals are created, a simple way to load and run a script is:
+ *
+ * although {@code require} could also be used:
+ *
+ * The standard globals will contain all standard libraries plus {@code luajava}:
+ *
+ * The debug globals are simply the standard globals plus the {@code debug} library {@link DebugLib}.
+ *
+ * The class ensures that initialization is done in the correct order,
+ * and that linkage is made to {@link LuaThread#setGlobals(LuaValue)}.
+ * @see JmePlatform
+ */
public class JsePlatform {
/**
* Create a standard set of globals for JSE including all the libraries.
*
* @return Table of globals initialized with the standard JSE libraries
+ * @see #debugGlobals()
+ * @see JsePlatform
+ * @see JmePlatform
*/
public static LuaTable standardGlobals() {
LuaTable _G = new LuaTable();
@@ -52,7 +100,15 @@ public class JsePlatform {
LuaC.install();
return _G;
}
-
+
+ /** Create standard globals including the {@link debug} library.
+ *
+ * @return Table of globals initialized with the standard JSE and debug libraries
+ * @see #standardGlobals()
+ * @see JsePlatform
+ * @see JmePlatform
+ * @see DebugLib
+ */
public static LuaTable debugGlobals() {
LuaTable _G = standardGlobals();
_G.load(new DebugLib());
diff --git a/src/jse/org/luaj/vm2/lib/jse/LuajavaLib.java b/src/jse/org/luaj/vm2/lib/jse/LuajavaLib.java
index 548cd139..9b0eebb3 100644
--- a/src/jse/org/luaj/vm2/lib/jse/LuajavaLib.java
+++ b/src/jse/org/luaj/vm2/lib/jse/LuajavaLib.java
@@ -22,10 +22,6 @@
package org.luaj.vm2.lib.jse;
-/** LuaJava-like bindings to Java scripting.
- *
- * TODO: coerce types on way in and out, pick method base on arg count ant types.
- */
import java.lang.reflect.Array;
import java.lang.reflect.Constructor;
import java.lang.reflect.Field;
@@ -43,11 +39,48 @@ import org.luaj.vm2.LuaTable;
import org.luaj.vm2.LuaUserdata;
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.ThreeArgFunction;
import org.luaj.vm2.lib.TwoArgFunction;
import org.luaj.vm2.lib.VarArgFunction;
+/**
+ * Subclass of {@link LibFunction} which implements the features of the luajava package.
+ *
+ * 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
+ * {@link JsePlatform#standardGlobals()}
+ *
+ * To instantiate and use it directly,
+ * link it into your globals table via {@link LuaValue#load(LuaValue)} using code such as:
+ *
+ * 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 LuaC
+ * @see http://www.keplerproject.org/luajava/manual.html#luareference
+ */
public class LuajavaLib extends VarArgFunction {
static final int INIT = 0;
diff --git a/src/jse/org/luaj/vm2/luajc/LuaJC.java b/src/jse/org/luaj/vm2/luajc/LuaJC.java
index 9e53f7dc..bcf42e95 100644
--- a/src/jse/org/luaj/vm2/luajc/LuaJC.java
+++ b/src/jse/org/luaj/vm2/luajc/LuaJC.java
@@ -32,6 +32,30 @@ import org.luaj.vm2.Prototype;
import org.luaj.vm2.LoadState.LuaCompiler;
import org.luaj.vm2.compiler.LuaC;
+/**
+ * Implementation of {@link LuaCompiler} which does direct
+ * lua-to-java-bytecode compiling.
+ *
+ * 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
+ * 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) ) );
+ * }
+ * Doing so will ensure the library is properly initialized
+ * and loaded into the globals table.
+ *
+ *
+ * {@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() );
+ * }
+ * Doing so will ensure the library is properly initialized
+ * and loaded into the globals table.
+ * {@code
+ * LuaTable _G = new LuaTable();
+ * LuaThread.setGlobals(_G);
+ * _G.load(new BaseLib());
+ * _G.load(new PackageLib());
+ * System.out.println( _G.get("require").call(LuaValue.valueOf("hyperbolic")) );
+ * }
+ * In practice, the first 4 lines of the above are minimal requirements to get
+ * and initialize a globals table capable of basic reqire, print, and other functions,
+ * so it is much more convenient to use the {@link JsePlatform} and {@link JmePlatform}
+ * utility classes instead.
+ * {@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") ) );
+ * }
+ * Doing so will ensure the library is properly initialized
+ * and loaded into the globals table.
+ * {@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 ) );
+ * }
+ * Doing so will ensure the library is properly initialized
+ * and loaded into the globals table.
+ * {@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"));
+ * }
+ * Doing so will ensure the library is properly initialized
+ * and loaded into the globals table.
+ *
+ *
+ * {@code
+ * LuaValue _G = JmePlatform.standardGlobals();
+ * _G.get("print").call(LuaValue.valueOf("hello, world"));
+ * }
+ * {@code
+ * LoadState.load( getClass().getResourceAsStream("main.lua"), "main.lua", _G ).call();
+ * }
+ * {@code
+ * _G.get("require").call(LuaValue.valueOf("main"));
+ * }
+ * For this to succeed, the file "main.lua" must be a resource in the class path.
+ * See {@link BaseLib} for details on finding scripts using {@link ResourceFinder}.
+ *
+ *
+ * In addition, the {@link LuaC} compiler is installed so lua files may be loaded in their source form.
+ * {@code
+ * LuaTable _G = new LuaTable();
+ * LuaThread.setGlobals(_G);
+ * _G.load(new JseBaseLib());
+ * _G.get("print").call(LuaValue.valueOf("hello, world"));
+ * }
+ * Doing so will ensure the library is properly initialized
+ * and loaded into the globals table.
+ * {@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"));
+ * }
+ * Doing so will ensure the library is properly initialized
+ * and loaded into the globals table.
+ * {@code
+ * LuaTable _G = new LuaTable();
+ * LuaThread.setGlobals(_G);
+ * _G.load(new JseBaseLib());
+ * _G.load(new PackageLib());
+ * _G.load(new JseMathLib());
+ * System.out.println( _G.get("math").get("sqrt").call( LuaValue.valueOf(2) ) );
+ * }
+ * Doing so will ensure the library is properly initialized
+ * and loaded into the globals table.
+ *
+ *
+ * {@code
+ * LuaTable _G = new LuaTable();
+ * LuaThread.setGlobals(_G);
+ * _G.load(new JseBaseLib());
+ * _G.load(new PackageLib());
+ * _G.load(new JseOsLib());
+ * System.out.println( _G.get("os").get("time").call() );
+ * }
+ * Doing so will ensure the library is properly initialized
+ * and loaded into the globals table.
+ * {@code
+ * LuaValue _G = JsePlatform.standardGlobals();
+ * _G.get("print").call(LuaValue.valueOf("hello, world"));
+ * }
+ * {@code
+ * LoadState.load( new FileInputStream("main.lua"), "main.lua", _G ).call();
+ * }
+ * {@code
+ * _G.get("require").call(LuaValue.valueOf("main"));
+ * }
+ * For this to succeed, the file "main.lua" must be in the current directory or a resource.
+ * See {@link JseBaseLib} for details on finding scripts using {@link ResourceFinder}.
+ *
+ *
+ * In addition, the {@link LuaC} compiler is installed so lua files may be loaded in their source form.
+ * {@code
+ * LuaTable _G = new LuaTable();
+ * LuaThread.setGlobals(_G);
+ * LuaC.install();
+ * _G.load(new BaseLib());
+ * _G.load(new PackageLib());
+ * _G.load(new LuajavaLib());
+ * _G.get("loadstring").call( LuaValue.valueOf(
+ * "sys = luajava.bindClass('java.lang.System')\n"+
+ * "print ( sys:currentTimeMillis() )\n" ) ).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
+ * on all JSE platforms via the call to {@link JsePlatform#standardGlobals()}
+ * and the luajava api's are simply invoked from lua.
+ * {@code
+ * LuaValue _G = JsePlatform.standardGlobals();
+ * LuaJC.install();
+ * LoadState.load( new ByteArrayInputStream("print 'hello'".getBytes()), "main.lua", _G ).call();
+ * }
+ * @see LuaCompiler
+ * @see LuaC
+ * @see JsePlatform
+ * @see JmePlatform
+ * @see BaseLib
+ * @see LuaValue
+ */
public class LuaJC implements LuaCompiler {
private static final String NON_IDENTIFIER = "[^a-zA-Z0-9_$/.\\-]";