From 4fb425bb161f21bf4d53daa93405706627e31a3b Mon Sep 17 00:00:00 2001 From: James Roseborough Date: Sat, 22 Jan 2011 01:00:20 +0000 Subject: [PATCH] Add javadoc content to source files. --- build.xml | 9 +- src/core/org/luaj/vm2/LoadState.java | 32 ++++- src/core/org/luaj/vm2/LuaFunction.java | 3 + src/core/org/luaj/vm2/LuaNil.java | 3 +- src/core/org/luaj/vm2/LuaNumber.java | 1 + src/core/org/luaj/vm2/LuaTable.java | 7 +- src/core/org/luaj/vm2/LuaThread.java | 85 +++++++++++- src/core/org/luaj/vm2/LuaValue.java | 59 +++++--- src/core/org/luaj/vm2/Varargs.java | 14 +- src/core/org/luaj/vm2/compiler/LuaC.java | 15 +- src/core/org/luaj/vm2/lib/BaseLib.java | 48 +++++-- src/core/org/luaj/vm2/lib/CoroutineLib.java | 30 +++- src/core/org/luaj/vm2/lib/DebugLib.java | 30 +++- src/core/org/luaj/vm2/lib/IoLib.java | 43 +++++- src/core/org/luaj/vm2/lib/LibFunction.java | 130 +++++++++++++++++- src/core/org/luaj/vm2/lib/MathLib.java | 49 ++++++- src/core/org/luaj/vm2/lib/OneArgFunction.java | 28 +++- src/core/org/luaj/vm2/lib/OsLib.java | 50 +++++-- src/core/org/luaj/vm2/lib/PackageLib.java | 35 ++++- src/core/org/luaj/vm2/lib/ResourceFinder.java | 21 ++- src/core/org/luaj/vm2/lib/StringLib.java | 29 +++- src/core/org/luaj/vm2/lib/TableLib.java | 31 +++++ .../org/luaj/vm2/lib/ThreeArgFunction.java | 26 ++++ src/core/org/luaj/vm2/lib/TwoArgFunction.java | 26 ++++ src/core/org/luaj/vm2/lib/VarArgFunction.java | 21 +++ .../org/luaj/vm2/lib/ZeroArgFunction.java | 26 +++- src/jme/org/luaj/vm2/lib/jme/JmeIoLib.java | 38 ++++- src/jme/org/luaj/vm2/lib/jme/JmePlatform.java | 67 +++++++++ .../org/luaj/vm2/lib/jse/CoerceJavaToLua.java | 8 +- .../org/luaj/vm2/lib/jse/CoerceLuaToJava.java | 8 +- src/jse/org/luaj/vm2/lib/jse/JseBaseLib.java | 43 +++++- src/jse/org/luaj/vm2/lib/jse/JseIoLib.java | 34 ++++- src/jse/org/luaj/vm2/lib/jse/JseMathLib.java | 38 ++++- src/jse/org/luaj/vm2/lib/jse/JseOsLib.java | 50 +++++-- src/jse/org/luaj/vm2/lib/jse/JsePlatform.java | 60 +++++++- src/jse/org/luaj/vm2/lib/jse/LuajavaLib.java | 41 +++++- src/jse/org/luaj/vm2/luajc/LuaJC.java | 24 ++++ 37 files changed, 1129 insertions(+), 133 deletions(-) diff --git a/build.xml b/build.xml index bb153b00..cc2a7682 100644 --- a/build.xml +++ b/build.xml @@ -5,6 +5,7 @@ + @@ -130,6 +131,12 @@ + + + + + + @@ -190,6 +197,6 @@ basedir="build" includes="luaj-${version}/**"/> - + diff --git a/src/core/org/luaj/vm2/LoadState.java b/src/core/org/luaj/vm2/LoadState.java index 60bfe7a6..9528e315 100644 --- a/src/core/org/luaj/vm2/LoadState.java +++ b/src/core/org/luaj/vm2/LoadState.java @@ -25,14 +25,44 @@ import java.io.DataInputStream; import java.io.IOException; import java.io.InputStream; + /** -* Class to manage loading of {@link Prototype} instances. +* Class to manage loading of {@link Prototype} instances. *

+* The {@link LoadState} class exposes one main function, +* namely {@link #load(InputStream, String, LuaValue)}, +* to be used to load code from a particular input stream. +*

+* 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; *
    *
  • {@link LuaValue#tableOf()} empty table
    • *
  • {@link LuaValue#tableOf(int, int)} table with capacity
    • - *
  • {@link LuaValue#tableOf(LuaValue[])} initialize array part
    • - *
  • {@link LuaValue#tableOf(Varargs, int)} initialize array part
    • + *
  • {@link LuaValue#listOf(LuaValue[])} initialize array part
    • + *
  • {@link LuaValue#listOf(LuaValue[], Varargs)} initialize array part
    • + *
  • {@link LuaValue#tableOf(LuaValue[])} initialize named hash part
    • + *
  • {@link LuaValue#tableOf(Varargs, int)} initialize named hash part
    • *
  • {@link LuaValue#tableOf(LuaValue[], LuaValue[])} initialize array and named parts
    • *
  • {@link LuaValue#tableOf(LuaValue[], LuaValue[], Varargs)} initialize array and named parts
    • *
+ * @see LuaValue */ public class LuaTable extends LuaValue { private static final int MIN_HASH_CAPACITY = 2; diff --git a/src/core/org/luaj/vm2/LuaThread.java b/src/core/org/luaj/vm2/LuaThread.java index 01a34374..97e87456 100644 --- a/src/core/org/luaj/vm2/LuaThread.java +++ b/src/core/org/luaj/vm2/LuaThread.java @@ -23,10 +23,38 @@ package org.luaj.vm2; import org.luaj.vm2.lib.DebugLib; - - /** - * Implementation of lua coroutines using Java Threads + * Subclass of {@link LuaValue} that implements + * a lua coroutine thread using Java Threads. + *

+ * 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: + *

    + *
  • {@link #listOf(LuaValue[])} for unnamed elements
    • + *
  • {@link #tableOf(LuaValue[])} for named elements
    • + *
  • {@link #tableOf(LuaValue[], LuaValue[], Varargs)} for mixtures
    • + *
+ *

+ * 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. + *

    + *
  • {@link ZeroArgFunction}
    • + *
  • {@link OneArgFunction}
    • + *
  • {@link TwoArgFunction}
    • + *
  • {@link ThreeArgFunction}
    • + *
  • {@link VarArgFunction}
    • + *
+ *

+ * 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 + * It contains only the math library support that is possible on JME. + * For a more complete implementation based on math functions specific to JSE + * use {@link org.luaj.vm2.lib.jse.JseMathLib}. + * In Particular the following math functions are not implemented by this library: + *

    + *
  • acos
    • + *
  • asin
    • + *
  • atan
    • + *
  • cosh
    • + *
  • log
    • + *
  • log10
    • + *
  • sinh
    • + *
  • tanh
    • + *
  • atan2
    • + *
+ *

+ * 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: + * 

 {@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. + *

+ * 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: - * - *

  • execute()
    • - *
  • remove()
    • - *
  • rename()
    • - *
  • tmpname()
    • - * - * - * @see org.luaj.vm2.lib.jse.JseOsLib + *

    + * 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: + *

      + *
    • {@code execute()}
      • + *
    • {@code remove()}
      • + *
    • {@code rename()}
      • + *
    • {@code tmpname()}
      • + *
    + *

    + * 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.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. + *

    + * @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: + * 

     {@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. + *

    + * 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: + * 

     {@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. + *

    + * 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: + * 

     {@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. + *

    + * 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: + * 

     {@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. + *

    + * 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 + *

      + *
    • Some math functions are not implemented, see {@link MathLib} for details
      • + *
    • Scripts are loaded via Class.getResourceAsStream(), see {@link BaseLib} for details
      • + *
    • OS functions execute(), remove(), rename(), and tmpname() vary, see {@link OsLib} for details
      • + *
    • I/O seek is not implemented, see {@link JmeIoLib} for details
      • + *
    • luajava is not available, see {@link LuajavaLib} for details
      • + *
    + *

    + * 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: + * 

     {@code
+ * LuaValue _G = JmePlatform.standardGlobals();
+ * _G.get("print").call(LuaValue.valueOf("hello, world"));
+ * }
    + *

    + * Once globals are created, a simple way to load and run a script is: + * 

     {@code
+ * LoadState.load( getClass().getResourceAsStream("main.lua"), "main.lua", _G ).call();
+ * }
    + *

    + * although {@code require} could also be used: + * 

     {@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}. + *

    + * The standard globals will contain all standard libraries in their JME flavors: + *

      + *
    • {@link BaseLib}
      • + *
    • {@link PackageLib}
      • + *
    • {@link TableLib}
      • + *
    • {@link StringLib}
      • + *
    • {@link CoroutineLib}
      • + *
    • {@link MathLib}
      • + *
    • {@link JmeIoLib}
      • + *
    • {@link OsLib}
      • + *
    + * In addition, the {@link LuaC} compiler is installed so lua files may be loaded in their source form. + *

    + * 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: + * 

     {@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. + *

    + * 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: + * 

     {@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. + *

    + * 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: + * 

     {@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. + *

    + * 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: - * - *

  • execute()
    • - *
  • remove()
    • - *
  • rename()
    • - *
  • tmpname()
    • - * - * - * @see org.luaj.vm2.lib.OsLib + * Subclass of {@link LibFunction} which implements the standard lua {@code os} library. + *

    + * This contains more complete implementations of the following functions + * using features that are specific to JSE: + *

      + *
    • {@code execute()}
      • + *
    • {@code remove()}
      • + *
    • {@code rename()}
      • + *
    • {@code tmpname()}
      • + *
    + *

    + * 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: + * 

     {@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. + *

    + * @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: + * 

     {@code
+ * LuaValue _G = JsePlatform.standardGlobals();
+ * _G.get("print").call(LuaValue.valueOf("hello, world"));
+ * }
    + *

    + * Once globals are created, a simple way to load and run a script is: + * 

     {@code
+ * LoadState.load( new FileInputStream("main.lua"), "main.lua", _G ).call();
+ * }
    + *

    + * although {@code require} could also be used: + * 

     {@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}. + *

    + * The standard globals will contain all standard libraries plus {@code luajava}: + *

      + *
    • {@link JseBaseLib}
      • + *
    • {@link PackageLib}
      • + *
    • {@link TableLib}
      • + *
    • {@link StringLib}
      • + *
    • {@link CoroutineLib}
      • + *
    • {@link JseMathLib}
      • + *
    • {@link JseIoLib}
      • + *
    • {@link JseOsLib}
      • + *
    • {@link LuajavaLib}
      • + *
    + * In addition, the {@link LuaC} compiler is installed so lua files may be loaded in their source form. + *

    + * 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: + * 

     {@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. + *

    + * 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
+ * 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_$/.\\-]";