open-autonomous-connection/luaj
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 2 Wiki Activity

Add javadoc content to source files.

Browse Source
This commit is contained in:
James Roseborough
2011-01-22 01:00:20 +00:00
parent 1a648fef56
commit 4fb425bb16
37 changed files with 1129 additions and 133 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
build.xml
View File

@@ -5,6 +5,7 @@
<property name="jar.name.jme" value="luaj-jme-${version}.jar"/>
<property name="jar.name.jse" value="luaj-jse-${version}.jar"/>
<property name="jar.name.jse.sources" value="luaj-jse.sources-${version}.jar"/>
<import file="wtk.xml"/>
@@ -130,6 +131,12 @@
</jar>
</target>
<target name="jar-jse-sources" depends="compile">
<jar destfile="${jar.name.jse.sources}">
<fileset dir="build/jse/src"/>
</jar>
</target>
<target name="doc">
<delete dir="docs/api"/>
<mkdir dir="docs/api"/>
@@ -190,6 +197,6 @@
basedir="build" includes="luaj-${version}/**"/>
</target>
<target name="all" depends="clean,jar-jme,jar-jse"/>
<target name="all" depends="clean,jar-jme,jar-jse,jar-jse-sources"/>
</project>

32
src/core/org/luaj/vm2/LoadState.java
View File

@@ -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.
* <p>
* 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.
* <p>
* A simple pattern for loading and executing code is
* <pre> {@code
* LuaValue _G = JsePlatform.standardGlobals();
* LoadState.load( new FileInputStream("main.lua"), "main.lua", _G ).call();
* } </pre>
* This should work regardless of which {@link LuaCompiler}
* has been installed.
* <p>
*
* Prior to loading code, a compiler should be installed.
* <p>
* By default, when using {@link JsePlatform} or {@JmePlatform}
* to construct globals, the {@link LuaC} compiler is installed.
* <p>
* To override the default compiler with, say, the {@link LuaJC}
* lua-to-java bytecode compiler, install it before loading,
* for example:
* <pre> {@code
* LuaValue _G = JsePlatform.standardGlobals();
* LuaJC.install();
* LoadState.load( new FileInputStream("main.lua"), "main.lua", _G ).call();
* } </pre>
*
* @see LuaCompiler
* @see LuaClosure
* @see LuaFunction
* @see LoadState#compiler
* @see LoadState#load(InputStream, String, LuaValue)
* @see LuaC
* @see LuaJC
*/
public class LoadState {

3
src/core/org/luaj/vm2/LuaFunction.java
View File

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

3
src/core/org/luaj/vm2/LuaNil.java
View File

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

1
src/core/org/luaj/vm2/LuaNumber.java
View File

@@ -28,6 +28,7 @@ package org.luaj.vm2;
* and {@link LuaDouble} which holds all other number values.
* @see LuaInteger
* @see LuaDouble
* @see LuaValue
*
*/
abstract

7
src/core/org/luaj/vm2/LuaTable.java
View File

@@ -60,11 +60,14 @@ import java.util.Vector;
* <ul>
* <li>{@link LuaValue#tableOf()} empty table</li>
* <li>{@link LuaValue#tableOf(int, int)} table with capacity</li>
* <li>{@link LuaValue#tableOf(LuaValue[])} initialize array part</li>
* <li>{@link LuaValue#tableOf(Varargs, int)} initialize array part</li>
* <li>{@link LuaValue#listOf(LuaValue[])} initialize array part</li>
* <li>{@link LuaValue#listOf(LuaValue[], Varargs)} initialize array part</li>
* <li>{@link LuaValue#tableOf(LuaValue[])} initialize named hash part</li>
* <li>{@link LuaValue#tableOf(Varargs, int)} initialize named hash part</li>
* <li>{@link LuaValue#tableOf(LuaValue[], LuaValue[])} initialize array and named parts</li>
* <li>{@link LuaValue#tableOf(LuaValue[], LuaValue[], Varargs)} initialize array and named parts</li>
* </ul>
* @see LuaValue
*/
public class LuaTable extends LuaValue {
private static final int MIN_HASH_CAPACITY = 2;

85
src/core/org/luaj/vm2/LuaThread.java
View File

@@ -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.
* <p>
* A LuaThread is typically created in response to a scripted call to
* {@code coroutine.create()}
* <p>
* 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.
* <p>
* 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.
* <p>
* 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.
* <p>
* 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 ) {

59
src/core/org/luaj/vm2/LuaValue.java
View File

@@ -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}.
* <p>
* 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.
* <p>
* 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.
* <p>
* 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) );
* } </pre>
* <p>
* To load and run a script, {@link LoadState} is used:
* <pre> {@code
* LoadState.load( new FileInputStream("main.lua"), "main.lua", globals ).call();
* } </pre>
* <p>
* although {@code require} could also be used:
* <pre> {@code
* globals.get("require").call(LuaValue.valueOf("main"));
* } </pre>
* 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.
* <p>
* 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.
* <p>
* 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:
* <ul>
* <li>{@link #listOf(LuaValue[])} for unnamed elements</li>
* <li>{@link #tableOf(LuaValue[])} for named elements</li>
* <li>{@link #tableOf(LuaValue[], LuaValue[], Varargs)} for mixtures</li>
* </ul>
* <p>
* 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}
* <p>
* 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 {

14
src/core/org/luaj/vm2/Varargs.java
View File

@@ -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)}
* <p>
* @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 {

15
src/core/org/luaj/vm2/compiler/LuaC.java
View File

@@ -36,7 +36,6 @@ import org.luaj.vm2.LuaValue;
import org.luaj.vm2.Prototype;
import org.luaj.vm2.LoadState.LuaCompiler;
/**
* Compiler for Lua.
* <p>
@@ -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.
* <p>
* 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:
* <pre> {@code
* LuaValue _G = JsePlatform.standardGlobals();
* LoadState.load( new ByteArrayInputStream("print 'hello'".getBytes()), "main.lua", _G ).call();
* } </pre>
* @see LuaCompiler
* @see LuaJC
* @see JsePlatform
* @see JmePlatform
* @see BaseLib
* @see LuaValue
* @see LuaCompiler
* @see Prototype
*/

48
src/core/org/luaj/vm2/lib/BaseLib.java
View File

@@ -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.
* <p>
* 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.
* <p>
* To use basic library functions that include a {@link ResourceFinder} based on
* directory lookup, use {@link JseBaseLib} instead.
* <p>
* Typically, this library is included as part of a call to either
* {@link JmePlatform#standardGlobals()}
* <p>
* To instantiate and use it directly,
* link it into your globals table via {@link LuaValue#load(LuaValue)} using code such as:
* <pre> {@code
* LuaTable _G = new LuaTable();
* LuaThread.setGlobals(_G);
* _G.load(new BaseLib());
* _G.get("print").call(LuaValue.valueOf("hello, world"));
* } </pre>
* Doing so will ensure the library is properly initialized
* and loaded into the globals table.
* <p>
* This is a direct port of the corresponding library in C.
* @see JseBaseLib
* @see ResourceFinder
* @see #FINDER
* @see LibFunction
* @see JsePlatform
* @see JmePlatform
* @see <a href="http://www.lua.org/manual/5.1/manual.html#5.1">http://www.lua.org/manual/5.1/manual.html#5.1</a>
*/
public class BaseLib extends OneArgFunction implements ResourceFinder {
public static final String VERSION = "Luaj 2.0";

30
src/core/org/luaj/vm2/lib/CoroutineLib.java
View File

@@ -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.
* <p>
* 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.
* <p>
* Typically, this library is included as part of a call to either
* {@link JsePlatform#standardGlobals()} or {@link JmePlatform#standardGlobals()}
* <p>
* To instantiate and use it directly,
* link it into your globals table via {@link LuaValue#load(LuaValue)} using code such as:
* <pre> {@code
* LuaTable _G = new LuaTable();
* _G.load(new CoroutineLib());
* } </pre>
* Doing so will ensure the library is properly initialized
* and loaded into the globals table.
* <p>
* @see LibFunction
* @see JsePlatform
* @see JmePlatform
* @see <a href="http://www.lua.org/manual/5.1/manual.html#5.2">http://www.lua.org/manual/5.1/manual.html#5.2</a>
*/
public class CoroutineLib extends VarArgFunction {
private static final int INIT = 0;

30
src/core/org/luaj/vm2/lib/DebugLib.java
View File

@@ -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.
* <p>
* 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.
* <p>
* Typically, this library is included as part of a call to either
* {@link JsePlatform#debugGlobals()} or {@link JmePlatform#debugGlobals()}
* <p>
* To instantiate and use it directly,
* link it into your globals table via {@link LuaValue#load(LuaValue)} using code such as:
* <pre> {@code
* LuaTable _G = new LuaTable();
* _G.load(new DebugLib());
* } </pre>
* Doing so will ensure the library is properly initialized
* and loaded into the globals table.
* <p>
* @see LibFunction
* @see JsePlatform
* @see JmePlatform
* @see <a href="http://www.lua.org/manual/5.1/manual.html#5.9">http://www.lua.org/manual/5.1/manual.html#5.9</a>
*/
public class DebugLib extends VarArgFunction {
public static final boolean CALLS = (null != System.getProperty("CALLS"));
public static final boolean TRACE = (null != System.getProperty("TRACE"));

43
src/core/org/luaj/vm2/lib/IoLib.java
View File

@@ -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.
* <p>
* 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.
* <p>
* 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.
* <p>
* Typically, this library is included as part of a call to either
* {@link JsePlatform#standardGlobals()} or {@link JmePlatform#standardGlobals()}
* <p>
* To instantiate and use it directly,
* link it into your globals table via {@link LuaValue#load(LuaValue)} using code such as:
* <pre> {@code
* LuaTable _G = new LuaTable();
* _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"));
* } </pre>
* Doing so will ensure the library is properly initialized
* and loaded into the globals table.
* <p>
* This has been implemented to match as closely as possible the behavior in the corresponding library in C.
* @see LibFunction
* @see JsePlatform
* @see JmePlatform
* @see JseIoLib
* @see JmeIoLib
* @see <a href="http://www.lua.org/manual/5.1/manual.html#5.7">http://www.lua.org/manual/5.1/manual.html#5.7</a>
*/
abstract
public class IoLib extends OneArgFunction {

130
src/core/org/luaj/vm2/lib/LibFunction.java
View File

@@ -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.
* <p>
* 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.
* <p>
* 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.
* <p>
* 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.
* <ul>
* <li>{@link ZeroArgFunction}</li>
* <li>{@link OneArgFunction}</li>
* <li>{@link TwoArgFunction}</li>
* <li>{@link ThreeArgFunction}</li>
* <li>{@link VarArgFunction}</li>
* </ul>
* <p>
* 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.
* <p>
* For example, the following code will implement a library called "hyperbolic"
* with two functions, "sinh", and "cosh":
* <pre> {@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);
* }
* }
* }
* }</pre>
* 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.
* <p>
* To test it, a script such as this can be used:
* <pre> {@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) )
* }</pre>
* <p>
* It should produce something like:
* <pre> {@code
* t table: 3dbbd23f
* hyperbolic table: 3dbbd23f
* k,v cosh cosh
* k,v sinh sinh
* sinh(.5) 0.5210953
* cosh(.5) 1.127626
* }</pre>
* <p>
* 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.
* <p>
* 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.
* <p>
* 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.
* <p>
* 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
* <p>
* 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<n; i++ ) {
@@ -55,17 +177,17 @@ abstract public class LibFunction extends LuaFunction {
}
}
// allocate storage for upvalue, leave it empty
/** Java code generation utility to allocate storage for upvalue, leave it empty */
protected static LuaValue[] newupe() {
return new LuaValue[1];
}
// allocate storage for upvalue, initialize with nil
/** Java code generation utility to allocate storage for upvalue, initialize with nil */
protected static LuaValue[] newupn() {
return new LuaValue[] { NIL };
}
// allocate storage for upvalue, initialize with value
/** Java code generation utility to allocate storage for upvalue, initialize with value */
protected static LuaValue[] newupl(LuaValue v) {
return new LuaValue[] { v };
}

49
src/core/org/luaj/vm2/lib/MathLib.java
View File

@@ -29,11 +29,50 @@ import org.luaj.vm2.LuaValue;
import org.luaj.vm2.Varargs;
/**
* Base math library with JME support.
*
* For j2se support use org.luaj.lib.j2se.MathLib
*
* @see org.luaj.vm2.lib.jse.JseMathLib
* Subclass of {@link LibFunction} which implements the lua standard {@code math}
* library.
* <p>
* 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 <b>not</b> implemented by this library:
* <ul>
* <li>acos</li>
* <li>asin</li>
* <li>atan</li>
* <li>cosh</li>
* <li>log</li>
* <li>log10</li>
* <li>sinh</li>
* <li>tanh</li>
* <li>atan2</li>
* </ul>
* <p>
* 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.
* <p>
* Typically, this library is included as part of a call to either
* {@link JmePlatform#standardGlobals()}
* <p>
* To instantiate and use it directly,
* link it into your globals table via {@link LuaValue#load(LuaValue)} using code such as:
* <pre> {@code
* LuaTable _G = new LuaTable();
* LuaThread.setGlobals(_G);
* _G.load(new BaseLib());
* _G.load(new PackageLib());
* _G.load(new MathLib());
* System.out.println( _G.get("math").get("sqrt").call( LuaValue.valueOf(2) ) );
* } </pre>
* Doing so will ensure the library is properly initialized
* and loaded into the globals table.
* <p>
* 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 <a href="http://www.lua.org/manual/5.1/manual.html#5.6">http://www.lua.org/manual/5.1/manual.html#5.6</a>
*/
public class MathLib extends OneArgFunction {

28
src/core/org/luaj/vm2/lib/OneArgFunction.java
View File

@@ -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.
* <p>
* 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.
* <p>
* 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}.
* <p>
* 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;
}

50
src/core/org/luaj/vm2/lib/OsLib.java
View File

@@ -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.
* <p>
* It is a usable base with simplified stub functions
* for library functions that cannot be implemented uniformly
* on Jse and Jme.
*
* <p>
* This can be installed as-is on either platform, or extended
* and refined to be used in a complete Jse implementation.
*
* <p>Contains limited implementations of features not supported well on Jme:
* <bl>
* <li>execute()</li>
* <li>remove()</li>
* <li>rename()</li>
* <li>tmpname()</li>
* </bl>
*
* @see org.luaj.vm2.lib.jse.JseOsLib
* <p>
* 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.
* <p>
* The following functions have limited implementations of features
* that are not supported well on Jme:
* <ul>
* <li>{@code execute()}</li>
* <li>{@code remove()}</li>
* <li>{@code rename()}</li>
* <li>{@code tmpname()}</li>
* </ul>
* <p>
* Typically, this library is included as part of a call to either
* {@link JmePlatform#standardGlobals()}
* <p>
* To instantiate and use it directly,
* link it into your globals table via {@link LuaValue#load(LuaValue)} using code such as:
* <pre> {@code
* LuaTable _G = new LuaTable();
* LuaThread.setGlobals(_G);
* _G.load(new BaseLib());
* _G.load(new PackageLib());
* _G.load(new OsLib());
* System.out.println( _G.get("os").get("time").call() );
* } </pre>
* Doing so will ensure the library is properly initialized
* and loaded into the globals table.
* <p>
* @see LibFunction
* @see JseOsLib
* @see JsePlatform
* @see JmePlatform
* @see <a href="http://www.lua.org/manual/5.1/manual.html#5.8">http://www.lua.org/manual/5.1/manual.html#5.8</a>
*/
public class OsLib extends VarArgFunction {
public static String TMP_PREFIX = ".luaj";

35
src/core/org/luaj/vm2/lib/PackageLib.java
View File

@@ -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.
*
* <p>
* Typically, this library is included as part of a call to either
* {@link JsePlatform#standardGlobals()} or {@link JmePlatform#standardGlobals()}
* <p>
* To instantiate and use it directly,
* link it into your globals table via {@link LuaValue#load(LuaValue)} using code such as:
* <pre> {@code
* LuaTable _G = new LuaTable();
* LuaThread.setGlobals(_G);
* _G.load(new BaseLib());
* _G.load(new PackageLib());
* System.out.println( _G.get("require").call(LuaValue.valueOf("hyperbolic")) );
* } </pre>
* 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.
* <p>
* This has been implemented to match as closely as possible the behavior in the corresponding library in C.
* However, the default filesystem search semantics are different and delegated to the bas library
* as outlined in the {@link BaseLib} and {@link JseBaseLib} documetnation.
* @see LibFunction
* @see BaseLib
* @see JseBaseLib
* @see JsePlatform
* @see JmePlatform
* @see <a href="http://www.lua.org/manual/5.1/manual.html#5.3">http://www.lua.org/manual/5.1/manual.html#5.3</a>
*/
public class PackageLib extends OneArgFunction {
public static String DEFAULT_LUA_PATH = "?.lua";

21
src/core/org/luaj/vm2/lib/ResourceFinder.java
View File

@@ -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.
*
* <p>
* 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.
* <p>
* 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)}.
* <p>
* The io library does not use this API for file manipulation.
* <p>
* @see BaseLib
* @see BaseLib#FINDER
* @see JseBaseLib
* @see JmePlatform
* @see JsePlatform
*/
public interface ResourceFinder {

29
src/core/org/luaj/vm2/lib/StringLib.java
View File

@@ -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.
*
* <p>
* Typically, this library is included as part of a call to either
* {@link JsePlatform#standardGlobals()} or {@link JmePlatform#standardGlobals()}
* <p>
* To instantiate and use it directly,
* link it into your globals table via {@link LuaValue#load(LuaValue)} using code such as:
* <pre> {@code
* LuaTable _G = new LuaTable();
* 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") ) );
* } </pre>
* Doing so will ensure the library is properly initialized
* and loaded into the globals table.
* <p>
* This is a direct port of the corresponding library in C.
* @see LibFunction
* @see JsePlatform
* @see JmePlatform
* @see <a href="http://www.lua.org/manual/5.1/manual.html#5.4">http://www.lua.org/manual/5.1/manual.html#5.4</a>
*/
public class StringLib extends OneArgFunction {
public static LuaTable instance;

31
src/core/org/luaj/vm2/lib/TableLib.java
View File

@@ -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.
*
* <p>
* Typically, this library is included as part of a call to either
* {@link JsePlatform#standardGlobals()} or {@link JmePlatform#standardGlobals()}
* <p>
* To instantiate and use it directly,
* link it into your globals table via {@link LuaValue#load(LuaValue)} using code such as:
* <pre> {@code
* LuaTable _G = new LuaTable();
* 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 ) );
* } </pre>
* Doing so will ensure the library is properly initialized
* and loaded into the globals table.
* <p>
* This has been implemented to match as closely as possible the behavior in the corresponding library in C.
* @see LibFunction
* @see JsePlatform
* @see JmePlatform
* @see <a href="http://www.lua.org/manual/5.1/manual.html#5.5">http://www.lua.org/manual/5.1/manual.html#5.5</a>
*/
public class TableLib extends OneArgFunction {
public TableLib() {

26
src/core/org/luaj/vm2/lib/ThreeArgFunction.java
View File

@@ -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.
* <p>
* 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.
* <p>
* 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}.
* <p>
* 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;
}

26
src/core/org/luaj/vm2/lib/TwoArgFunction.java
View File

@@ -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.
* <p>
* 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.
* <p>
* 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}.
* <p>
* 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;
}

21
src/core/org/luaj/vm2/lib/VarArgFunction.java
View File

@@ -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.
* <p>
* 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.
* <p>
* If between one and three arguments are required, and only one return value is returned,
* {@link ZeroArgFunction}, {@link OneArgFunction}, {@link TwoArgFunction}, or {@link ThreeArgFunction}.
* <p>
* 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() {
}

26
src/core/org/luaj/vm2/lib/ZeroArgFunction.java
View File

@@ -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.
* <p>
* 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.
* <p>
* 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}.
* <p>
* 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;
}

38
src/jme/org/luaj/vm2/lib/jme/JmeIoLib.java
View File

@@ -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.
* <p>
* The implementation of the is based on CLDC 1.0 and StreamConnection.
* However, seek is not supported.
* <p>
* Typically, this library is included as part of a call to
* {@link JmePlatform#standardGlobals()}
* <p>
* To instantiate and use it directly,
* link it into your globals table via {@link LuaValue#load(LuaValue)} using code such as:
* <pre> {@code
* LuaTable _G = new LuaTable();
* LuaThread.setGlobals(_G);
* _G.load(new BaseLib());
* _G.load(new PackageLib());
* _G.load(new JmeIoLib());
* _G.get("io").get("write").call(LuaValue.valueOf("hello, world\n"));
* } </pre>
* Doing so will ensure the library is properly initialized
* and loaded into the globals table.
* <p>
* This has been implemented to match as closely as possible the behavior in the corresponding library in C.
* @see LibFunction
* @see JsePlatform
* @see JmePlatform
* @see IoLib
* @see JseIoLib
* @see <a href="http://www.lua.org/manual/5.1/manual.html#5.6">http://www.lua.org/manual/5.1/manual.html#5.6</a>
*/
public class JmeIoLib extends IoLib {

67
src/jme/org/luaj/vm2/lib/jme/JmePlatform.java
View File

@@ -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.
* <p>
* The JME platform, being limited, cannot implement all libraries in all aspects. The main limitations are
* <ul>
* <li>Some math functions are not implemented, see {@link MathLib} for details</li>
* <li>Scripts are loaded via Class.getResourceAsStream(), see {@link BaseLib} for details</li>
* <li>OS functions execute(), remove(), rename(), and tmpname() vary, see {@link OsLib} for details</li>
* <li>I/O seek is not implemented, see {@link JmeIoLib} for details</li>
* <li>luajava is not available, see {@link LuajavaLib} for details</li>
* </ul>
* <p>
* It is used to allocate either a set of standard globals using
* {@link #standardGlobals()} or debug globals using {@link #debugGlobals()}
* <p>
* A simple example of initializing globals and using them from Java is:
* <pre> {@code
* LuaValue _G = JmePlatform.standardGlobals();
* _G.get("print").call(LuaValue.valueOf("hello, world"));
* } </pre>
* <p>
* Once globals are created, a simple way to load and run a script is:
* <pre> {@code
* LoadState.load( getClass().getResourceAsStream("main.lua"), "main.lua", _G ).call();
* } </pre>
* <p>
* although {@code require} could also be used:
* <pre> {@code
* _G.get("require").call(LuaValue.valueOf("main"));
* } </pre>
* For this to succeed, the file "main.lua" must be a resource in the class path.
* See {@link BaseLib} for details on finding scripts using {@link ResourceFinder}.
* <p>
* The standard globals will contain all standard libraries in their JME flavors:
* <ul>
* <li>{@link BaseLib}</li>
* <li>{@link PackageLib}</li>
* <li>{@link TableLib}</li>
* <li>{@link StringLib}</li>
* <li>{@link CoroutineLib}</li>
* <li>{@link MathLib}</li>
* <li>{@link JmeIoLib}</li>
* <li>{@link OsLib}</li>
* </ul>
* In addition, the {@link LuaC} compiler is installed so lua files may be loaded in their source form.
* <p>
* The debug globals are simply the standard globals plus the {@code debug} library {@link DebugLib}.
* <p>
* <p>
* 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());

8
src/jse/org/luaj/vm2/lib/jse/CoerceJavaToLua.java
View File

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

8
src/jse/org/luaj/vm2/lib/jse/CoerceLuaToJava.java
View File

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

43
src/jse/org/luaj/vm2/lib/jse/JseBaseLib.java
View File

@@ -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}.
* <p>
* 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}.
* <p>
* Typically, this library is included as part of a call to
* {@link JsePlatform#standardGlobals()}
* <p>
* To instantiate and use it directly,
* link it into your globals table via {@link LuaValue#load(LuaValue)} using code such as:
* <pre> {@code
* LuaTable _G = new LuaTable();
* LuaThread.setGlobals(_G);
* _G.load(new JseBaseLib());
* _G.get("print").call(LuaValue.valueOf("hello, world"));
* } </pre>
* Doing so will ensure the library is properly initialized
* and loaded into the globals table.
* <p>
* This is a direct port of the corresponding library in C.
* @see BaseLib
* @see ResourceFinder
* @see #FINDER
* @see LibFunction
* @see JsePlatform
* @see JmePlatform
* @see <a href="http://www.lua.org/manual/5.1/manual.html#5.1">http://www.lua.org/manual/5.1/manual.html#5.1</a>
*/
public class JseBaseLib extends org.luaj.vm2.lib.BaseLib {
/** Construct a JSE base library instance */

34
src/jse/org/luaj/vm2/lib/jse/JseIoLib.java
View File

@@ -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.
* <p>
* It uses RandomAccessFile to implement seek on files.
* <p>
* Typically, this library is included as part of a call to
* {@link JsePlatform#standardGlobals()}
* <p>
* To instantiate and use it directly,
* link it into your globals table via {@link LuaValue#load(LuaValue)} using code such as:
* <pre> {@code
* LuaTable _G = new LuaTable();
* LuaThread.setGlobals(_G);
* _G.load(new JseBaseLib());
* _G.load(new PackageLib());
* _G.load(new JseIoLib());
* _G.get("io").get("write").call(LuaValue.valueOf("hello, world\n"));
* } </pre>
* Doing so will ensure the library is properly initialized
* and loaded into the globals table.
* <p>
* This has been implemented to match as closely as possible the behavior in the corresponding library in C.
* @see LibFunction
* @see JsePlatform
* @see JmePlatform
* @see IoLib
* @see JmeIoLib
* @see <a href="http://www.lua.org/manual/5.1/manual.html#5.7">http://www.lua.org/manual/5.1/manual.html#5.7</a>
*/
public class JseIoLib extends IoLib {

38
src/jse/org/luaj/vm2/lib/jse/JseMathLib.java
View File

@@ -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.
* <p>
* It contains all lua math functions, including those not available on the JME platform.
* See {@link org.luaj.lib.MathLib} for the exception list.
* <p>
* Typically, this library is included as part of a call to
* {@link JsePlatform#standardGlobals()}
* <p>
* To instantiate and use it directly,
* link it into your globals table via {@link LuaValue#load(LuaValue)} using code such as:
* <pre> {@code
* LuaTable _G = new LuaTable();
* LuaThread.setGlobals(_G);
* _G.load(new JseBaseLib());
* _G.load(new PackageLib());
* _G.load(new JseMathLib());
* System.out.println( _G.get("math").get("sqrt").call( LuaValue.valueOf(2) ) );
* } </pre>
* Doing so will ensure the library is properly initialized
* and loaded into the globals table.
* <p>
* 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 <a href="http://www.lua.org/manual/5.1/manual.html#5.6">http://www.lua.org/manual/5.1/manual.html#5.6</a>
*/
public class JseMathLib extends org.luaj.vm2.lib.MathLib {

50
src/jse/org/luaj/vm2/lib/jse/JseOsLib.java
View File

@@ -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.
*
* <p>Implements features specific to the J2se environment:
* <bl>
* <li>execute()</li>
* <li>remove()</li>
* <li>rename()</li>
* <li>tmpname()</li>
* </bl>
*
* @see org.luaj.vm2.lib.OsLib
* Subclass of {@link LibFunction} which implements the standard lua {@code os} library.
* <p>
* This contains more complete implementations of the following functions
* using features that are specific to JSE:
* <ul>
* <li>{@code execute()}</li>
* <li>{@code remove()}</li>
* <li>{@code rename()}</li>
* <li>{@code tmpname()}</li>
* </ul>
* <p>
* 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.
* <p>
* Typically, this library is included as part of a call to either
* {@link JsePlatform#standardGlobals()}
* <p>
* To instantiate and use it directly,
* link it into your globals table via {@link LuaValue#load(LuaValue)} using code such as:
* <pre> {@code
* LuaTable _G = new LuaTable();
* LuaThread.setGlobals(_G);
* _G.load(new JseBaseLib());
* _G.load(new PackageLib());
* _G.load(new JseOsLib());
* System.out.println( _G.get("os").get("time").call() );
* } </pre>
* Doing so will ensure the library is properly initialized
* and loaded into the globals table.
* <p>
* @see LibFunction
* @see OsLib
* @see JsePlatform
* @see JmePlatform
* @see <a href="http://www.lua.org/manual/5.1/manual.html#5.8">http://www.lua.org/manual/5.1/manual.html#5.8</a>
*/
public class JseOsLib extends org.luaj.vm2.lib.OsLib {

60
src/jse/org/luaj/vm2/lib/jse/JsePlatform.java
View File

@@ -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.
* <p>
* It is used to allocate either a set of standard globals using
* {@link #standardGlobals()} or debug globals using {@link #debugGlobals()}
* <p>
* A simple example of initializing globals and using them from Java is:
* <pre> {@code
* LuaValue _G = JsePlatform.standardGlobals();
* _G.get("print").call(LuaValue.valueOf("hello, world"));
* } </pre>
* <p>
* Once globals are created, a simple way to load and run a script is:
* <pre> {@code
* LoadState.load( new FileInputStream("main.lua"), "main.lua", _G ).call();
* } </pre>
* <p>
* although {@code require} could also be used:
* <pre> {@code
* _G.get("require").call(LuaValue.valueOf("main"));
* } </pre>
* For this to succeed, the file "main.lua" must be in the current directory or a resource.
* See {@link JseBaseLib} for details on finding scripts using {@link ResourceFinder}.
* <p>
* The standard globals will contain all standard libraries plus {@code luajava}:
* <ul>
* <li>{@link JseBaseLib}</li>
* <li>{@link PackageLib}</li>
* <li>{@link TableLib}</li>
* <li>{@link StringLib}</li>
* <li>{@link CoroutineLib}</li>
* <li>{@link JseMathLib}</li>
* <li>{@link JseIoLib}</li>
* <li>{@link JseOsLib}</li>
* <li>{@link LuajavaLib}</li>
* </ul>
* In addition, the {@link LuaC} compiler is installed so lua files may be loaded in their source form.
* <p>
* The debug globals are simply the standard globals plus the {@code debug} library {@link DebugLib}.
* <p>
* 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());

41
src/jse/org/luaj/vm2/lib/jse/LuajavaLib.java
View File

@@ -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.
* <p>
* Luajava is an approach to mixing lua and java using simple functions that bind
* java classes and methods to lua dynamically. The API is documented on the
* <a href="http://www.keplerproject.org/luajava/">luajava</a> documentation pages.
* <p>
* Typically, this library is included as part of a call to either
* {@link JsePlatform#standardGlobals()}
* <p>
* To instantiate and use it directly,
* link it into your globals table via {@link LuaValue#load(LuaValue)} using code such as:
* <pre> {@code
* LuaTable _G = new LuaTable();
* LuaThread.setGlobals(_G);
* 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();
* } </pre>
* 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.
* <p>
* This has been implemented to match as closely as possible the behavior in the corresponding library in C.
* @see LibFunction
* @see JsePlatform
* @see JmePlatform
* @see LuaC
* @see <a href="http://www.keplerproject.org/luajava/manual.html#luareference">http://www.keplerproject.org/luajava/manual.html#luareference</a>
*/
public class LuajavaLib extends VarArgFunction {
static final int INIT = 0;

24
src/jse/org/luaj/vm2/luajc/LuaJC.java
View File

@@ -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.
* <p>
* This requires the bcel library to be on the class path to work as expected.
* If the library is not found, the default {@link LuaC} lua-to-lua-bytecode
* compiler will be used.
* <p>
* The compiler should be installed as part of globals initialization,
* and before any scripts or lua code is executed.
* A typical example is to install it following the globals creation,
* as in the following:
* <pre> {@code
* LuaValue _G = JsePlatform.standardGlobals();
* LuaJC.install();
* LoadState.load( new ByteArrayInputStream("print 'hello'".getBytes()), "main.lua", _G ).call();
* } </pre>
* @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_$/.\\-]";