/*
* $Id: LuaState.java 157 2012-10-05 23:00:17Z andre@naef.com $
* See LICENSE.txt for license terms.
*/
package com.naef.jnlua;
import java.io.ByteArrayInputStream;
import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
import java.lang.ref.PhantomReference;
import java.lang.ref.ReferenceQueue;
import java.lang.reflect.InvocationHandler;
import java.lang.reflect.Method;
import java.lang.reflect.Proxy;
import java.util.HashSet;
import java.util.Set;
import com.naef.jnlua.JavaReflector.Metamethod;
/**
* JNLua core class representing a Lua instance.
*
* <p>
* The class performs extensive checking on all arguments and its state.
* Specifically, the following exceptions are thrown under the indicated
* conditions:
* </p>
*
* <table class="doc">
* <tr>
* <th>Exception</th>
* <th>When</th>
* </tr>
* <tr>
* <td>{@link java.lang.NullPointerException}</td>
* <td>if an argument is <code>null</code> and the API does not explicitly
* specify that the argument may be <code>null</code></td>
* </tr>
* <tr>
* <td>{@link java.lang.IllegalStateException}</td>
* <td>if the Lua state is closed and the API does not explicitly specify that
* the method may be invoked on a closed Lua state</td>
* </tr>
* <tr>
* <td>{@link java.lang.IllegalArgumentException}</td>
* <td>if a stack index refers to a non-valid stack location and the API does
* not explicitly specify that the stack index may be non-valid</td>
* </tr>
* <tr>
* <td>{@link java.lang.IllegalArgumentException}</td>
* <td>if a stack index refers to an stack location with value type that is
* different from the value type explicitly specified in the API</td>
* </tr>
* <tr>
* <td>{@link java.lang.IllegalArgumentException}</td>
* <td>if a count is negative or out of range and the API does not explicitly
* specify that the count may be negative or out of range</td>
* </tr>
* <tr>
* <td>{@link com.naef.jnlua.LuaRuntimeException}</td>
* <td>if a Lua runtime error occurs</td>
* </tr>
* <tr>
* <td>{@link com.naef.jnlua.LuaSyntaxException}</td>
* <td>if the syntax of a Lua chunk is incorrect</td>
* </tr>
* <tr>
* <td>{@link com.naef.jnlua.LuaMemoryAllocationException}</td>
* <td>if the Lua memory allocator runs out of memory or if a JNI allocation
* fails</td>
* </tr>
* <tr>
* <td>{@link com.naef.jnlua.LuaGcMetamethodException}</td>
* <td>if an error occurs running a <code>__gc</code> metamethod during garbage
* collection</td>
* </tr>
* <tr>
* <td>{@link com.naef.jnlua.LuaMessageHandlerException}</td>
* <td>if an error occurs running the message handler of a protected call</td>
* </tr>
* </table>
*/
public class LuaState {
// -- Static
/**
* Multiple returns pseudo return value count.
*/
public static final int MULTRET = -1;
/**
* Registry pseudo-index.
*/
public static final int REGISTRYINDEX;
/**
* OK status.
*
* @since JNLua 1.0.0
*/
public static final int OK = 0;
/**
* Status indicating that a thread is suspended.
*/
public static final int YIELD = 1;
/**
* Registry index of the main thread.
*
* @since JNLua 1.0.0
*/
public static final int RIDX_MAINTHREAD = 1;
/**
* Registry index of the global environment.
*
* @since JNLua 1.0.0
*/
public static final int RIDX_GLOBALS = 2;
/**
* The JNLua version. The format is <major>.<minor>.
*/
public static final String VERSION = "1.0";
/**
* The Lua version. The format is <major>.<minor>.
*/
public static final String LUA_VERSION;
static {
NativeSupport.getInstance().getLoader().load();
REGISTRYINDEX = lua_registryindex();
LUA_VERSION = lua_version();
}
/**
* The API version.
*/
private static final int APIVERSION = 3;
// -- State
/**
* Whether the <code>lua_State</code> on the JNI side is owned by the Java
* state and must be closed when the Java state closes.
*/
private boolean ownState;
/**
* The <code>lua_State</code> pointer on the JNI side. <code>0</code>
* implies that this Lua state is closed. The field is modified exclusively
* on the JNI side and must not be touched on the Java side.
*/
private long luaState;
/**
* The <code>lua_State</code> pointer on the JNI side for the running
* coroutine. This field is modified exclusively on the JNI side and must
* not be touched on the Java side.
*/
private long luaThread;
/**
* The yield flag. This field is modified from both the JNI side and Java
* side and signals a pending yield.
*/
private boolean yield;
/**
* Ensures proper finalization of this Lua state.
*/
private Object finalizeGuardian;
/**
* The class loader for dynamically loading classes.
*/
private ClassLoader classLoader;
/**
* Reflects Java objects.
*/
private JavaReflector javaReflector;
/**
* Converts between Lua types and Java types.
*/
private Converter converter;
/**
* Set of Lua proxy phantom references for pre-mortem cleanup.
*/
private Set<LuaValueProxyRef> proxySet = new HashSet<LuaValueProxyRef>();
/**
* Reference queue for pre-mortem cleanup.
*/
private ReferenceQueue<LuaValueProxyImpl> proxyQueue = new ReferenceQueue<LuaValueProxyImpl>();
// -- Construction
/**
* Creates a new instance. The class loader of this Lua state is set to the
* context class loader of the calling thread. The Java reflector and the
* converter are initialized with the default implementations.
*
* @see #getClassLoader()
* @see #setClassLoader(ClassLoader)
* @see #getJavaReflector()
* @see #setJavaReflector(JavaReflector)
* @see #getConverter()
* @see #setConverter(Converter)
*/
public LuaState() {
this(0L);
}
/**
* Creates a new instance.
*/
private LuaState(long luaState) {
ownState = luaState == 0L;
lua_newstate(APIVERSION, luaState);
check();
// Create a finalize guardian
finalizeGuardian = new Object() {
@Override
public void finalize() {
synchronized (LuaState.this) {
closeInternal();
}
}
};
// Add metamethods
for (int i = 0; i < JavaReflector.Metamethod.values().length; i++) {
final JavaReflector.Metamethod metamethod = JavaReflector.Metamethod
.values()[i];
lua_pushjavafunction(new JavaFunction() {
@Override
public int invoke(LuaState luaState) {
JavaFunction javaFunction = getMetamethod(
luaState.toJavaObjectRaw(1), metamethod);
if (javaFunction != null) {
return javaFunction.invoke(LuaState.this);
} else {
throw new UnsupportedOperationException(
metamethod.getMetamethodName());
}
}
});
lua_setfield(-2, metamethod.getMetamethodName());
}
lua_pop(1);
// Set fields
classLoader = Thread.currentThread().getContextClassLoader();
javaReflector = DefaultJavaReflector.getInstance();
converter = DefaultConverter.getInstance();
}
// -- Properties
/**
* Returns the class loader of this Lua state. The class loader is used for
* dynamically loading classes.
*
* <p>
* The method may be invoked on a closed Lua state.
* </p>
*
* @return the class loader
*/
public synchronized ClassLoader getClassLoader() {
return classLoader;
}
/**
* Sets the class loader of this Lua state. The class loader is used for
* dynamically loading classes.
*
* <p>
* The method may be invoked on a closed Lua state.
* </p>
*
* @param classLoader
* the class loader to set
*/
public synchronized void setClassLoader(ClassLoader classLoader) {
if (classLoader == null) {
throw new NullPointerException();
}
this.classLoader = classLoader;
}
/**
* Returns the Java reflector of this Lua state.
*
* <p>
* The method may be invoked on a closed Lua state.
* </p>
*
* @return the Java reflector converter
*/
public synchronized JavaReflector getJavaReflector() {
return javaReflector;
}
/**
* Sets the Java reflector of this Lua state.
*
* <p>
* The method may be invoked on a closed Lua state.
* </p>
*
* @param javaReflector
* the Java reflector
*/
public synchronized void setJavaReflector(JavaReflector javaReflector) {
if (javaReflector == null) {
throw new NullPointerException();
}
this.javaReflector = javaReflector;
}
/**
* Returns a metamethod for a specified object. If the object implements the
* {@link com.naef.jnlua.JavaReflector} interface, the metamethod is first
* queried from the object. If the object provides the requested metamethod,
* that metamethod is returned. Otherwise, the method returns the metamethod
* provided by the Java reflector configured in this Lua state.
*
* <p>
* Clients requiring access to metamethods should go by this method to
* ensure consistent class-by-class overriding of the Java reflector.
* </p>
*
* @param obj
* the object, or <code>null</code>
* @return the Java reflector
*/
public synchronized JavaFunction getMetamethod(Object obj,
Metamethod metamethod) {
if (obj != null && obj instanceof JavaReflector) {
JavaFunction javaFunction = ((JavaReflector) obj)
.getMetamethod(metamethod);
if (javaFunction != null) {
return javaFunction;
}
}
return javaReflector.getMetamethod(metamethod);
}
/**
* Returns the converter of this Lua state.
*
* <p>
* The method may be invoked on a closed Lua state.
* </p>
*
* @return the converter
*/
public synchronized Converter getConverter() {
return converter;
}
/**
* Sets the converter of this Lua state.
*
* <p>
* The method may be invoked on a closed Lua state.
* </p>
*
* @param converter
* the converter
*/
public synchronized void setConverter(Converter converter) {
if (converter == null) {
throw new NullPointerException();
}
this.converter = converter;
}
// -- Life cycle
/**
* Returns whether this Lua state is open.
*
* <p>
* The method may be invoked on a closed Lua state.
* </p>
*
* @return whether this Lua state is open
*/
public final synchronized boolean isOpen() {
return isOpenInternal();
}
/**
* Closes this Lua state and releases all resources.
*
* <p>
* The method may be invoked on a closed Lua state and has no effect in that
* case.
* </p>
*/
public synchronized void close() {
closeInternal();
}
/**
* Performs a garbage collection operation. Please see the Lua Reference
* Manual for an explanation of the actions, arguments and return values.
*
* @param what
* the operation to perform
* @param data
* the argument required by some operations
* @return a return value depending on the GC operation performed
*/
public synchronized int gc(GcAction what, int data) {
check();
return lua_gc(what.ordinal(), data);
}
// -- Registration
/**
* Opens the specified library in this Lua state. The library is pushed onto
* the stack.
*
* @param library
* the library
*/
public synchronized void openLib(Library library) {
check();
library.open(this);
}
/**
* Opens the Lua standard libraries and the JNLua Java module in this Lua
* state.
*
* <p>
* The method opens all libraries defined by the {@link Library}
* enumeration.
* </p>
*/
public synchronized void openLibs() {
check();
for (Library library : Library.values()) {
library.open(this);
pop(1);
}
}
/**
* Registers a named Java function as a global variable.
*
* @param namedJavaFunction
* the Java function to register
*/
public synchronized void register(NamedJavaFunction namedJavaFunction) {
check();
String name = namedJavaFunction.getName();
if (name == null) {
throw new IllegalArgumentException("anonymous function");
}
pushJavaFunction(namedJavaFunction);
setGlobal(name);
}
/**
* Registers a module and pushes the module on the stack. Optionally, a
* module can be registered globally. As of Lua 5.2, modules are <i>not</i>
* expected to set global variables anymore.
*
* @param moduleName
* the module name
* @param namedJavaFunctions
* the Java functions of the module
* @param global
* whether to register the module globally
*/
public synchronized void register(String moduleName,
NamedJavaFunction[] namedJavaFunctions, boolean global) {
check();
/*
* The following code corresponds to luaL_requiref() and must be kept in
* sync. The original code cannot be called due to the necessity of
* pushing each C function with an individual closure.
*/
newTable(0, namedJavaFunctions.length);
for (int i = 0; i < namedJavaFunctions.length; i++) {
String name = namedJavaFunctions[i].getName();
if (name == null) {
throw new IllegalArgumentException(String.format(
"anonymous function at index %d", i));
}
pushJavaFunction(namedJavaFunctions[i]);
setField(-2, name);
}
lua_getsubtable(REGISTRYINDEX, "_LOADED");
pushValue(-2);
setField(-2, moduleName);
pop(1);
if (global) {
rawGet(REGISTRYINDEX, RIDX_GLOBALS);
pushValue(-2);
setField(-2, moduleName);
pop(1);
}
}
// -- Load and dump
/**
* Loads a Lua chunk from an input stream and pushes it on the stack as a
* function. Depending on the value of mode, the the Lua chunk can either be
* a pre-compiled binary chunk or a UTF-8 encoded text chunk.
*
* @param inputStream
* the input stream
* @param chunkName
* the name of the chunk for use in error messages
* @param mode
* <code>"b"</code> to accept binary, <code>"t"</code> to accept
* text, or <code>"bt"</code> to accept both
* @throws IOException
* if an IO error occurs
*/
public synchronized void load(InputStream inputStream, String chunkName,
String mode) throws IOException {
check();
lua_load(inputStream, chunkName, mode);
}
/**
* Loads a Lua chunk from a string and pushes it on the stack as a function.
* The string must contain a source chunk.
*
* @param chunk
* the Lua source chunk
* @param chunkName
* the name of the chunk for use in error messages
*/
public synchronized void load(String chunk, String chunkName) {
check();
try {
load(new ByteArrayInputStream(chunk.getBytes("UTF-8")), chunkName,
"t");
} catch (IOException e) {
throw new LuaMemoryAllocationException(e.getMessage(), e);
}
}
/**
* Dumps the function on top of the stack as a pre-compiled binary chunk
* into an output stream.
*
* @param outputStream
* the output stream
* @throws IOException
* if an IO error occurs
*/
public synchronized void dump(OutputStream outputStream) throws IOException {
check();
lua_dump(outputStream);
}
// -- Call
/**
* Calls a Lua function. The function to call and the specified number of
* arguments are on the stack. After the call, the specified number of
* returns values are on stack. If the number of return values has been
* specified as {@link #MULTRET}, the number of values on the stack
* corresponds the to number of values actually returned by the called
* function.
*
* @param argCount
* the number of arguments
* @param returnCount
* the number of return values, or {@link #MULTRET} to accept all
* values returned by the function
*/
public synchronized void call(int argCount, int returnCount) {
check();
lua_pcall(argCount, returnCount);
}
// -- Globals
/**
* Pushes the value of a global variable on the stack.
*
* @param name
* the global variable name
*/
public synchronized void getGlobal(String name) {
check();
lua_getglobal(name);
}
/**
* Sets the value on top of the stack as a global variable and pops the
* value from the stack.
*
* @param name
* the global variable name
*/
public synchronized void setGlobal(String name)
throws LuaMemoryAllocationException, LuaRuntimeException {
check();
lua_setglobal(name);
}
// -- Stack push
/**
* Pushes a boolean value on the stack.
*
* @param b
* the boolean value to push
*/
public synchronized void pushBoolean(boolean b) {
check();
lua_pushboolean(b ? 1 : 0);
}
/**
* Pushes a byte array value as a string value on the stack.
*
* @param b
* the byte array to push
*/
public synchronized void pushByteArray(byte[] b) {
check();
lua_pushbytearray(b);
}
/**
* Pushes an integer value as a number value on the stack.
*
* @param n
* the integer value to push
*/
public synchronized void pushInteger(int n) {
check();
lua_pushinteger(n);
}
/**
* Pushes a Java function on the stack.
*
* @param javaFunction
* the function to push
*/
public synchronized void pushJavaFunction(JavaFunction javaFunction) {
check();
lua_pushjavafunction(javaFunction);
}
/**
* Pushes a Java object on the stack with conversion. The object is
* processed the by the configured converter.
*
* @param object
* the Java object
* @see #getConverter()
* @see #setConverter(Converter)
*/
public synchronized void pushJavaObject(Object object) {
check();
getConverter().convertJavaObject(this, object);
}
/**
* Pushes a Java object on the stack. The object is pushed "as is", i.e.
* without conversion.
*
* <p>
* If you require to push a Lua value that represents the Java object, then
* invoke <code>pushJavaObject(object)</code>.
* </p>
*
* <p>
* You cannot push <code>null</code> without conversion since
* <code>null</code> is not a Java object. The converter converts
* <code>null</code> to <code>nil</code>.
* </p>
*
* @param object
* the Java object
* @see #pushJavaObject(Object)
*/
public synchronized void pushJavaObjectRaw(Object object) {
check();
lua_pushjavaobject(object);
}
/**
* Pushes a nil value on the stack.
*/
public synchronized void pushNil() {
check();
lua_pushnil();
}
/**
* Pushes a number value on the stack.
*
* @param n
* the number to push
*/
public synchronized void pushNumber(double n) {
check();
lua_pushnumber(n);
}
/**
* Pushes a string value on the stack.
*
* @param s
* the string value to push
*/
public synchronized void pushString(String s) {
check();
lua_pushstring(s);
}
// -- Stack type test
/**
* Returns whether the value at the specified stack index is a boolean.
*
* <p>
* The stack index may be non-valid.
* </p>
*
* @param index
* the stack index
* @return whether the value is a boolean
*/
public synchronized boolean isBoolean(int index) {
check();
return lua_isboolean(index) != 0;
}
/**
* Returns whether the value at the specified stack index is a C function.
*
* <p>
* The stack index may be non-valid.
* </p>
*
* @param index
* the stack index
* @return whether the value is a function
*/
public synchronized boolean isCFunction(int index) {
check();
return lua_iscfunction(index) != 0;
}
/**
* Returns whether the value at the specified stack index is a function
* (either a C function, a Java function or a Lua function.)
*
* <p>
* The stack index may be non-valid.
* </p>
*
* @param index
* the stack index
* @return whether the value is a function
*/
public synchronized boolean isFunction(int index) {
check();
return lua_isfunction(index) != 0;
}
/**
* Returns whether the value at the specified stack index is a Java
* function.
*
* <p>
* The stack index may be non-valid.
* </p>
*
* @param index
* the stack index
* @return whether the value is a function
*/
public synchronized boolean isJavaFunction(int index) {
check();
return lua_isjavafunction(index) != 0;
}
/**
* Returns whether the value at the specified stack index is convertible to
* a Java object of the specified type. The conversion is checked by the
* configured converter.
*
* <p>
* The stack index may be non-valid.
* </p>
*
* @param index
* the stack index
* @return whether the value is convertible to a Java object of the
* specified type
* @see #setConverter(Converter)
* @see #getConverter()
*/
public synchronized boolean isJavaObject(int index, Class<?> type) {
check();
return converter.getTypeDistance(this, index, type) != Integer.MAX_VALUE;
}
/**
* Returns whether the value at the specified stack index is a Java object.
*
* <p>
* Note that the method does not perform conversion. If you want to check if
* a value <i>is convertible to</i> a Java object, then invoke <code>
* isJavaObject(index, Object.class)</code>.
* </p>
*
* <p>
* The stack index may be non-valid.
* </p>
*
* @param index
* the stack index
* @return whether the value is a Java object
* @see #isJavaObject(int, Class)
*/
public synchronized boolean isJavaObjectRaw(int index) {
check();
return lua_isjavaobject(index) != 0;
}
/**
* Returns whether the value at the specified stack index is
* <code>nil</code>.
*
* <p>
* The stack index may be non-valid.
* </p>
*
* @param index
* the stack index
* @return whether the value is <code>nil</code>
*/
public synchronized boolean isNil(int index) {
check();
return lua_isnil(index) != 0;
}
/**
* Returns whether the specified stack index is non-valid.
*
* <p>
* The stack index may be non-valid.
* </p>
*
* @param index
* the stack index
* @return whether the stack index is non-valid
*/
public synchronized boolean isNone(int index) {
check();
return lua_isnone(index) != 0;
}
/**
* Returns whether the specified stack index is non-valid or its value is
* <code>nil</code>.
*
* <p>
* The stack index may be non-valid.
* </p>
*
* @param index
* the stack index
* @return whether the stack index is non-valid or its value is
* <code>nil</code>
*/
public synchronized boolean isNoneOrNil(int index) {
check();
return lua_isnoneornil(index) != 0;
}
/**
* Returns whether the value at the specified stack index is a number or a
* string convertible to a number.
*
* <p>
* The stack index may be non-valid.
* </p>
*
* @param index
* the stack index
* @return whether the value is a number or a string convertible to a number
*/
public synchronized boolean isNumber(int index) {
check();
return lua_isnumber(index) != 0;
}
/**
* Returns whether the value at the specified stack index is a string or a
* number (which is always convertible to a string.)
*
* <p>
* The stack index may be non-valid.
* </p>
*
* @param index
* the stack index
* @return whether the value is a string or a number
*/
public synchronized boolean isString(int index) {
check();
return lua_isstring(index) != 0;
}
/**
* Returns whether the value at the specified stack index is a table.
*
* <p>
* The stack index may be non-valid.
* </p>
*
* @param index
* the stack index
* @return whether the value is a table
*/
public synchronized boolean isTable(int index) {
check();
return lua_istable(index) != 0;
}
/**
* Returns whether the value at the specified stack index is a thread.
*
* <p>
* The stack index may be non-valid.
* </p>
*
* @param index
* the stack index
* @return whether the value is a thread
*/
public synchronized boolean isThread(int index) {
check();
return lua_isthread(index) != 0;
}
// -- Stack query
/**
* Compares the values at two specified stack indexes for the specified
* operator according to Lua semantics.
*
* <p>
* Any stack index may be non-valid in which case the method returns
* <code>false</code>.
* </p>
*
* @param index1
* the first stack index
* @param index2
* the second stack index
* @param operator
* the operator
* @return the result of the comparison
* @since JNLua 1.0.0
*/
public synchronized boolean compare(int index1, int index2,
RelOperator operator) {
check();
return lua_compare(index1, index2, operator.ordinal()) != 0;
}
/**
* Returns whether the values at two specified stack indexes are equal
* according to Lua semantics.
*
* @param index1
* the first stack index
* @param index2
* the second stack index
* @return whether the values are equal
* @deprecated instead use {@link #compare(int, int, RelOperator)}
*/
public synchronized boolean equal(int index1, int index2) {
return compare(index1, index2, RelOperator.EQ);
}
/**
* Returns the length of the value at the specified stack index. Please see
* the Lua Reference Manual for the definition of the raw length of a value.
*
* @param index
* the stack index
* @return the length
* @deprecated instead use {@link #rawLen(int)}
*/
public synchronized int length(int index) {
return rawLen(index);
}
/**
* Returns whether a value at a first stack index is less than the value at
* a second stack index according to Lua semantics.
*
* @param index1
* the first stack index
* @param index2
* the second stack index
* @return whether the value at the first index is less than the value at
* the second index
* @deprecated instead use {@link #compare(int, int, RelOperator)}
*/
public synchronized boolean lessThan(int index1, int index2)
throws LuaMemoryAllocationException, LuaRuntimeException {
return compare(index1, index2, RelOperator.LT);
}
/**
* Bypassing metatable logic, returns whether the values at two specified
* stack indexes are equal according to Lua semantics.
*
* <p>
* Any stack index may be non-valid in which case the method returns
* <code>false</code>.
* </p>
*
* @param index1
* the first stack index
* @param index2
* the second stack index
* @return whether the values are equal
*/
public synchronized boolean rawEqual(int index1, int index2) {
check();
return lua_rawequal(index1, index2) != 0;
}
/**
* Bypassing metatable logic, returns the length of the value at the
* specified stack index. Please see the Lua Reference Manual for the
* definition of the raw length of a value.
*
* @param index
* the stack index
* @return the length
* @since JNLua 1.0.0
*/
public synchronized int rawLen(int index) {
check();
return lua_rawlen(index);
}
/**
* Returns the boolean representation of the value at the specified stack
* index. The boolean representation is <code>true</code> for all values
* except <code>false</code> and <code>nil</code>. The method also returns
* <code>false</code> if the index is non-valid.
*
* @param index
* the stack index
* @return the boolean representation of the value
*/
public synchronized boolean toBoolean(int index) {
check();
return lua_toboolean(index) != 0;
}
/**
* Returns the byte array representation of the value at the specified stack
* index. The value must be a string or a number. If the value is a number,
* it is in place converted to a string. Otherwise, the method returns
* <code>null</code>.
*
* @param index
* the stack index
* @return the byte array representation of the value
*/
public synchronized byte[] toByteArray(int index) {
check();
return lua_tobytearray(index);
}
/**
* Returns the integer representation of the value at the specified stack
* index. The value must be a number or a string convertible to a number.
* Otherwise, the method returns <code>0</code>.
*
* @param index
* the stack index
* @return the integer representation, or <code>0</code>
*/
public synchronized int toInteger(int index) {
check();
return lua_tointeger(index);
}
/**
* Returns the integer representation of the value at the specified stack
* index. The value must be a number or a string convertible to a number.
* Otherwise, the method returns <code>null</code>.
*
* @param index
* the stack index
* @return the integer representation, or <code>null</code>
* @since JNLua 1.0.2
*/
public synchronized Integer toIntegerX(int index) {
check();
return lua_tointegerx(index);
}
/**
* Returns the Java function of the value at the specified stack index. If
* the value is not a Java function, the method returns <code>null</code>.
*
* @param index
* the stack index
* @return the Java function, or <code>null</code>
*/
public synchronized JavaFunction toJavaFunction(int index) {
check();
return lua_tojavafunction(index);
}
/**
* Returns a Java object of the specified type representing the value at the
* specified stack index. The value must be convertible to a Java object of
* the specified type. The conversion is executed by the configured
* converter.
*
* @param index
* the stack index
* @param type
* the Java type to convert to
* @return the object
* @throws ClassCastException
* if the conversion is not supported by the converter
* @see #getConverter()
* @see #setConverter(Converter)
*/
public synchronized <T> T toJavaObject(int index, Class<T> type) {
check();
return converter.convertLuaValue(this, index, type);
}
/**
* Returns the Java object of the value at the specified stack index. If the
* value is not a Java object, the method returns <code>null</code>.
*
* <p>
* Note that the method does not convert values to Java objects. If you
* require <i>any</i> Java object that represents the value at the specified
* index, then invoke <code>toJavaObject(index, Object.class)</code>.
* </p>
*
* @param index
* the stack index
* @return the Java object, or <code>null</code>
* @see #toJavaObject(int, Class)
*/
public synchronized Object toJavaObjectRaw(int index) {
check();
return lua_tojavaobject(index);
}
/**
* Returns the number representation of the value at the specified stack
* index. The value must be a number or a string convertible to a number.
* Otherwise, the method returns <code>0.0</code>.
*
* @param index
* the stack index
* @return the number representation, or <code>0.0</code>
*/
public synchronized double toNumber(int index) {
check();
return lua_tonumber(index);
}
/**
* Returns the number representation of the value at the specified stack
* index. The value must be a number or a string convertible to a number.
* Otherwise, the method returns <code>null</code>.
*
* @param index
* the stack index
* @return the number representation, or <code>null</code>
* @since JNLua 1.0.2
*/
public synchronized Double toNumberX(int index) {
check();
return lua_tonumberx(index);
}
/**
* Returns the pointer representation of the value at the specified stack
* index. The value must be a table, thread, function or userdata (such as a
* Java object.) Otherwise, the method returns <code>0L</code>. Different
* values return different pointers. Other than that, the returned value has
* no portable significance.
*
* @param index
* the stack index
* @return the pointer representation, or <code>0L</code> if none
*/
public synchronized long toPointer(int index) {
check();
return lua_topointer(index);
}
/**
* Returns the string representation of the value at the specified stack
* index. The value must be a string or a number. If the value is a number,
* it is in place converted to a string. Otherwise, the method returns
* <code>null</code>.
*
* @param index
* the stack index
* @return the string representation, or <code>null</code>
*/
public synchronized String toString(int index) {
check();
return lua_tostring(index);
}
/**
* Returns the type of the value at the specified stack index.
*
* <p>
* The stack index may be non-valid.
* </p>
*
* @param index
* the stack index
* @return the type, or <code>null</code> if the stack index is non-valid
*/
public synchronized LuaType type(int index) {
check();
int type = lua_type(index);
return type >= 0 ? LuaType.values()[type] : null;
}
/**
* Returns the name of the type at the specified stack index. The type name
* is the display text for the Lua type except for Java objects where the
* type name is the canonical class name.
*
* <p>
* The stack index may be non-valid in which case the method returns the
* string <code>"none"</code>.
* </p>
*
* @param index
* the index
* @return the type name
* @see LuaType#displayText()
* @see Class#getCanonicalName()
*/
public synchronized String typeName(int index) {
check();
LuaType type = type(index);
if (type == null) {
return "none";
}
switch (type) {
case USERDATA:
if (isJavaObjectRaw(index)) {
Object object = toJavaObjectRaw(index);
Class<?> clazz;
if (object instanceof Class<?>) {
clazz = (Class<?>) object;
} else {
clazz = object.getClass();
}
return clazz.getCanonicalName();
}
break;
}
return type.displayText();
}
// -- Stack operation
/**
* Returns the absolute stack index of the specified index.
*
* <p>
* The stack index may be non-valid.
* </p>
*
* @param index
* the stack index
* @return the absolute stack index
* @since JNLua 1.0.0
*/
public synchronized int absIndex(int index) {
check();
return lua_absindex(index);
}
/**
* Performs an arithmetic operation with values on top of the stack using
* Lua semantics.
*
* @param operator
* the operator to apply
* @since JNLua 1.0.0
*/
public synchronized void arith(ArithOperator operator) {
check();
lua_arith(operator.ordinal());
}
/**
* Concatenates the specified number values on top of the stack and replaces
* them with the concatenated value.
*
* @param n
* the number of values to concatenate
*/
public synchronized void concat(int n) {
check();
lua_concat(n);
}
/**
* Copies a value at a specified index to another index, replacing the value
* at that index.
*
* @param fromIndex
* the index to copy from
* @param toIndex
* the index to copy to
* @since JNLua 1.0.0
*/
public synchronized void copy(int fromIndex, int toIndex) {
check();
lua_copy(fromIndex, toIndex);
}
/**
* Returns the number of values on the stack.
*
* @return the number of values on the tack
*/
public synchronized int getTop() {
check();
return lua_gettop();
}
/**
* Pushes the length of the value at the specified stack index on the stack.
* The value pushed by the method corresponds to the Lua <code>#</code>
* operator.
*
* @param index
* the index for which to push the length
* @since JNLua 1.0.0
*/
public synchronized void len(int index) {
check();
lua_len(index);
}
/**
* Pops the value on top of the stack inserting it at the specified index
* and moving up elements above that index.
*
* @param index
* the stack index
*/
public synchronized void insert(int index) {
check();
lua_insert(index);
}
/**
* Pops values from the stack.
*
* @param count
* the number of values to pop
*/
public synchronized void pop(int count) {
check();
lua_pop(count);
}
/**
* Pushes the value at the specified index on top of the stack.
*
* @param index
* the stack index
*/
public synchronized void pushValue(int index) {
check();
lua_pushvalue(index);
}
/**
* Removes the value at the specified stack index moving down elements above
* that index.
*
* @param index
* the stack index
*/
public synchronized void remove(int index) {
check();
lua_remove(index);
}
/**
* Replaces the value at the specified index with the value popped from the
* top of the stack.
*
* @param index
* the stack index
*/
public synchronized void replace(int index) {
check();
lua_replace(index);
}
/**
* Sets the specified index as the new top of the stack.
*
* <p>
* The new top of the stack may be above the current top of the stack. In
* this case, new values are set to <code>nil</code>.
* </p>
*
* @param index
* the index of the new top of the stack
*/
public synchronized void setTop(int index) {
check();
lua_settop(index);
}
// -- Table
/**
* Pushes on the stack the value indexed by the key on top of the stack in
* the table at the specified index. The key is replaced by the value from
* the table.
*
* @param index
* the stack index containing the table
*/
public synchronized void getTable(int index) {
check();
lua_gettable(index);
}
/**
* Pushes on the stack the value indexed by the specified string key in the
* table at the specified index.
*
* @param index
* the stack index containing the table
* @param key
* the string key
*/
public synchronized void getField(int index, String key) {
check();
lua_getfield(index, key);
}
/**
* Creates a new table and pushes it on the stack.
*/
public synchronized void newTable() {
check();
lua_newtable();
}
/**
* Creates a new table with pre-allocated space for a number of array
* elements and record elements and pushes it on the stack.
*
* @param arrayCount
* the number of array elements
* @param recordCount
* the number of record elements
*/
public synchronized void newTable(int arrayCount, int recordCount) {
check();
lua_createtable(arrayCount, recordCount);
}
/**
* Pops a key from the stack and pushes on the stack the next key and its
* value in the table at the specified index. If there is no next key, the
* key is popped but nothing is pushed. The method returns whether there is
* a next key.
*
* @param index
* the stack index containing the table
* @return whether there is a next key
*/
public synchronized boolean next(int index) {
check();
return lua_next(index) != 0;
}
/**
* Bypassing metatable logic, pushes on the stack the value indexed by the
* key on top of the stack in the table at the specified index. The key is
* replaced by the value from the table.
*
* @param index
* the stack index containing the table
*/
public synchronized void rawGet(int index) {
check();
lua_rawget(index);
}
/**
* Bypassing metatable logic, pushes on the stack the value indexed by the
* specified integer key in the table at the specified index.
*
* @param index
* the stack index containing the table
* @param key
* the integer key
*/
public synchronized void rawGet(int index, int key) {
check();
lua_rawgeti(index, key);
}
/**
* Bypassing metatable logic, sets the value on top of the stack in the
* table at the specified index using the value on the second highest stack
* position as the key. Both the value and the key are popped from the
* stack.
*
* @param index
* the stack index containing the table
*/
public synchronized void rawSet(int index) {
check();
lua_rawset(index);
}
/**
* Bypassing metatable logic, sets the value on top of the stack in the
* table at the specified index using the specified integer key. The value
* is popped from the stack.
*
* @param index
* the stack index containing the table
* @param key
* the integer key
*/
public synchronized void rawSet(int index, int key) {
check();
lua_rawseti(index, key);
}
/**
* Sets the value on top of the stack in the table at the specified index
* using the value on the second highest stack position as the key. Both the
* value and the key are popped from the stack.
*
* @param index
* the stack index containing the table
*/
public synchronized void setTable(int index) {
check();
lua_settable(index);
}
/**
* Sets the value on top of the stack in the table at the specified index
* using the specified string key. The value is popped from the stack.
*
* @param index
* the stack index containing the table
* @param key
* the string key
*/
public synchronized void setField(int index, String key) {
check();
lua_setfield(index, key);
}
// -- Metatable
/**
* Pushes on the stack the value of the named field in the metatable of the
* value at the specified index and returns <code>true</code>. If the value
* does not have a metatable or if the metatable does not contain the named
* field, nothing is pushed and the method returns <code>false</code>.
*
* @param index
* the stack index containing the value to get the metafield from
* @param key
* the string key
* @return whether the metafield was pushed on the stack
*/
public synchronized boolean getMetafield(int index, String key) {
check();
return lua_getmetafield(index, key) != 0;
}
/**
* Pushes on the stack the metatable of the value at the specified index. If
* the value does not have a metatable, the method returns
* <code>false</code> and nothing is pushed.
*
* @param index
* the stack index containing the value to get the metatable from
* @return whether the metatable was pushed on the stack
*/
public synchronized boolean getMetatable(int index) {
check();
return lua_getmetatable(index) != 0;
}
/**
* Sets the value on top of the stack as the metatable of the value at the
* specified index. The metatable to be set is popped from the stack
* regardless whether it can be set or not.
*
* @param index
* the stack index containing the value to set the metatable for
*/
public synchronized void setMetatable(int index) {
check();
lua_setmetatable(index);
}
// -- Thread
/**
* Pops the start function of a new Lua thread from the stack and creates
* the new thread with that start function. The new thread is pushed on the
* stack.
*/
public synchronized void newThread() {
check();
lua_newthread();
}
/**
* Resumes the thread at the specified stack index, popping the specified
* number of arguments from the top of the stack and passing them to the
* resumed thread. The method returns the number of values pushed on the
* stack as the return values of the resumed thread.
*
* @param index
* the stack index containing the thread
* @param argCount
* the number of arguments to pass
* @return the number of values returned by the thread
*/
public synchronized int resume(int index, int argCount) {
check();
return lua_resume(index, argCount);
}
/**
* Returns the status of the thread at the specified stack index. If the
* thread is in initial state of has finished its execution, the method
* returns <code>0</code>. If the thread has yielded, the method returns
* {@link #YIELD}. Other return values indicate errors for which an
* exception has been thrown.
*
* @param index
* the index
* @return the status
*/
public synchronized int status(int index) {
check();
return lua_status(index);
}
/**
* Yields the running thread, popping the specified number of values from
* the top of the stack and passing them as return values to the thread
* which has resumed the running thread. The method must be used exclusively
* at the exit point of Java functions, i.e.
* <code>return luaState.yield(n)</code>.
*
* @param returnCount
* the number of results to pass
* @return the return value of the Java function
*/
public synchronized int yield(int returnCount) {
check();
yield = true;
return returnCount;
}
// -- Reference
/**
* Stores the value on top of the stack in the table at the specified index
* and returns the integer key of the value in that table as a reference.
* The value is popped from the stack.
*
* @param index
* the stack index containing the table where to store the value
* @return the reference integer key
* @see #unref(int, int)
*/
public synchronized int ref(int index) {
check();
return lua_ref(index);
}
/**
* Removes a previously created reference from the table at the specified
* index. The value is removed from the table and its integer key of the
* reference is freed for reuse.
*
* @param index
* the stack index containing the table where the value was
* stored
* @param reference
* the reference integer key
* @see #ref(int)
*/
public synchronized void unref(int index, int reference) {
check();
lua_unref(index, reference);
}
// -- Optimization
/**
* Counts the number of entries in a table.
*
* <p>
* The method provides optimized performance over a Java implementation of
* the same functionality due to the reduced number of JNI transitions.
* </p>
*
* @param index
* the stack index containing the table
* @return the number of entries in the table
*/
public synchronized int tableSize(int index) {
check();
return lua_tablesize(index);
}
/**
* Moves the specified number of sequential elements in a table used as an
* array from one index to another.
*
* <p>
* The method provides optimized performance over a Java implementation of
* the same functionality due to the reduced number of JNI transitions.
* </p>
*
* @param index
* the stack index containing the table
* @param from
* the index to move from
* @param to
* the index to move to
* @param count
* the number of elements to move
*/
public synchronized void tableMove(int index, int from, int to, int count) {
check();
lua_tablemove(index, from, to, count);
}
// -- Argument checking
/**
* Checks if a condition is true for the specified function argument. If
* not, the method throws a Lua runtime exception with the specified error
* message.
*
* @param index
* the argument index
* @param condition
* the condition
* @param msg
* the error message
*/
public synchronized void checkArg(int index, boolean condition, String msg) {
check();
if (!condition) {
throw getArgException(index, msg);
}
}
/**
* Checks if the value of the specified function argument is a string or a
* number. If so, the argument value is returned as a byte array. Otherwise,
* the method throws a Lua runtime exception with a descriptive error
* message.
*
* @param index
* the argument index
* @return the byte array value
*/
public synchronized byte[] checkByteArray(int index) {
check();
if (!isString(index)) {
throw getArgTypeException(index, LuaType.STRING);
}
return toByteArray(index);
}
/**
* Checks if the value of the specified function argument is a string or a
* number. If so, the argument value is returned as a byte array. If the
* value of the specified argument is undefined or <code>nil</code>, the
* method returns the specified default value. Otherwise, the method throws
* a Lua runtime exception with a descriptive error message.
*
* @param index
* the argument index
* @param d
* the default value
* @return the string value, or the default value
*/
public synchronized byte[] checkByteArray(int index, byte[] d) {
check();
if (isNoneOrNil(index)) {
return d;
}
return checkByteArray(index);
}
/**
* Checks if the value of the specified function argument is a string or a
* number matching the name of one of the specified enum values. If so, the
* argument value is returned as an enum value. Otherwise, the method throws
* a Lua runtime exception with a descriptive error message.
*
* @param index
* the argument index
* @param values
* the enum values
* @return the string value
* @since JNLua 1.0.0
*/
public synchronized <T extends Enum<T>> T checkEnum(int index, T[] values) {
check();
return checkEnum(index, values, null);
}
/**
* Checks if the value of the specified function argument is a string or a
* number matching one of the specified enum values. If so, the argument
* value is returned as an enum value. If the specified stack index is
* non-valid or if its value is <code>nil</code>, the method returns the
* specified default value. Otherwise, the method throws a Lua runtime
* exception with a descriptive error message.
*
* @param index
* the argument index
* @param values
* the enum values
* @param d
* the default value
* @return the string value, or the default value
* @since JNLua 1.0.0
*/
public synchronized <T extends Enum<T>> T checkEnum(int index, T[] values,
T d) {
check();
String s = d != null ? checkString(index, d.name())
: checkString(index);
for (int i = 0; i < values.length; i++) {
if (values[i].name().equals(s)) {
return values[i];
}
}
throw getArgException(index, String.format("invalid option '%s'", s));
}
/**
* Checks if the value of the specified function argument is a number or a
* string convertible to a number. If so, the argument value is returned as
* an integer. Otherwise, the method throws a Lua runtime exception with a
* descriptive error message.
*
* @param index
* the argument index
* @return the integer value
*/
public synchronized int checkInteger(int index) {
check();
Integer integer = toIntegerX(index);
if (integer == null) {
throw getArgTypeException(index, LuaType.NUMBER);
}
return integer.intValue();
}
/**
* Checks if the value of the specified function argument is a number or a
* string convertible to a number. If so, the argument value is returned as
* an integer. If the specified stack index is non-valid or if its value is
* <code>nil</code>, the method returns the specified default value.
* Otherwise, the method throws a Lua runtime exception with a descriptive
* error message.
*
* @param index
* the argument index
* @param d
* the default value
* @return the integer value, or the default value
*/
public synchronized int checkInteger(int index, int d) {
check();
if (isNoneOrNil(index)) {
return d;
}
return checkInteger(index);
}
/**
* Checks if the value of the specified function argument is convertible to
* a Java object of the specified type. If so, the argument value is
* returned as a Java object of the specified type. Otherwise, the method
* throws a Lua runtime exception with a descriptive error message.
*
* <p>
* Note that the converter converts <code>nil</code> to <code>null</code>.
* Therefore, the method may return <code>null</code> if the value is
* <code>nil</code>.
* </p>
*
* @param index
* the argument index
* @param clazz
* the expected type
* @return the Java object, or <code>null</code>
*/
public synchronized <T> T checkJavaObject(int index, Class<T> clazz) {
check();
if (!isJavaObject(index, clazz)) {
checkArg(
index,
false,
String.format("%s expected, got %s",
clazz.getCanonicalName(), typeName(index)));
}
return toJavaObject(index, clazz);
}
/**
* Checks if the value of the specified function argument is convertible to
* a Java object of the specified type. If so, the argument value is
* returned as a Java object of the specified type. If the specified stack
* index is non-valid or if its value is <code>nil</code>, the method
* returns the specified default value. Otherwise, the method throws a Lua
* runtime exception with a descriptive error message.
*
* @param index
* the argument index
* @param clazz
* the expected class
* @param d
* the default value
* @return the Java object, or the default value
*/
public synchronized <T> T checkJavaObject(int index, Class<T> clazz, T d) {
check();
if (isNoneOrNil(index)) {
return d;
}
return checkJavaObject(index, clazz);
}
/**
* Checks if the value of the specified function argument is a number or a
* string convertible to a number. If so, the argument value is returned as
* a number. Otherwise, the method throws a Lua runtime exception with a
* descriptive error message.
*
* @param index
* the argument index
* @return the number value
*/
public synchronized double checkNumber(int index) {
check();
Double number = toNumberX(index);
if (number == null) {
throw getArgTypeException(index, LuaType.NUMBER);
}
return number.doubleValue();
}
/**
* Checks if the value of the specified function argument is a number or a
* string convertible to a number. If so, the argument value is returned as
* a number. If the specified stack index is non-valid or if its value is
* <code>nil</code>, the method returns the specified default value.
* Otherwise, the method throws a Lua runtime exception with a descriptive
* error message.
*
* @param index
* the argument index
* @param d
* the default value
* @return the number value, or the default value
*/
public synchronized double checkNumber(int index, double d) {
check();
if (isNoneOrNil(index)) {
return d;
}
return checkNumber(index);
}
/**
* Checks if the value of the specified function argument is a string or a
* number matching one of the specified options. If so, the index position
* of the matched option is returned. Otherwise, the method throws a Lua
* runtime exception with a descriptive error message.
*
* @param index
* the argument index
* @param options
* the options
* @return the index position of the matched option
*/
public synchronized int checkOption(int index, String[] options) {
check();
return checkOption(index, options, null);
}
/**
* Checks if the value of the specified function argument is a string or a
* number matching one of the specified options. If so, the index position
* of the matched option is returned. If the specified stack index is
* non-valid or if its value is <code>nil</code>, the method matches the
* specified default value. If no match is found, the method throws a Lua
* runtime exception with a descriptive error message.
*
* @param index
* the argument index
* @param options
* the options
* @param d
* the default value
* @return the index position of the matched option
*/
public synchronized int checkOption(int index, String[] options, String d) {
check();
String s = d != null ? checkString(index, d) : checkString(index);
for (int i = 0; i < options.length; i++) {
if (options[i].equals(s)) {
return i;
}
}
throw getArgException(index, String.format("invalid option '%s'", s));
}
/**
* Checks if the value of the specified function argument is a string or a
* number. If so, the argument value is returned as a string. Otherwise, the
* method throws a Lua runtime exception with a descriptive error message.
*
* @param index
* the argument index
* @return the string value
*/
public synchronized String checkString(int index) {
check();
if (!isString(index)) {
throw getArgTypeException(index, LuaType.STRING);
}
return toString(index);
}
/**
* Checks if the value of the specified function argument is a string or a
* number. If so, the argument value is returned as a string. If the
* specified stack index is non-valid or if its value is <code>nil</code>,
* the method returns the specified default value. Otherwise, the method
* throws a Lua runtime exception with a descriptive error message.
*
* @param index
* the argument index
* @param d
* the default value
* @return the string value, or the default value
*/
public synchronized String checkString(int index, String d) {
check();
if (isNoneOrNil(index)) {
return d;
}
return checkString(index);
}
/**
* Checks if the value of the specified function argument is of the
* specified type. If not, the method throws a Lua runtime exception with a
* descriptive error message.
*
* @param index
* the argument index
* @param type
* the type
*/
public synchronized void checkType(int index, LuaType type) {
check();
if (type(index) != type) {
throw getArgTypeException(index, type);
}
}
// -- Proxy
/**
* Returns a proxy object for the Lua value at the specified index.
*
* @param index
* the stack index containing the Lua value
* @return the Lua value proxy
*/
public synchronized LuaValueProxy getProxy(int index) {
check();
pushValue(index);
return new LuaValueProxyImpl(ref(REGISTRYINDEX));
}
/**
* Returns a proxy object implementing the specified interface in Lua. The
* table at the specified stack index contains the method names from the
* interface as keys and the Lua functions implementing the interface
* methods as values. The returned object always implements the
* {@link LuaValueProxy} interface in addition to the specified interface.
*
* @param index
* the stack index containing the table
* @param interfaze
* the interface
* @return the proxy object
*/
@SuppressWarnings("unchecked")
public synchronized <T> T getProxy(int index, Class<T> interfaze) {
check();
return (T) getProxy(index, new Class<?>[] { interfaze });
}
/**
* Returns a proxy object implementing the specified list of interfaces in
* Lua. The table at the specified stack index contains the method names
* from the interfaces as keys and the Lua functions implementing the
* interface methods as values. The returned object always implements the
* {@link LuaValueProxy} interface in addition to the specified interfaces.
*
* @param index
* the stack index containing the table
* @param interfaces
* the interfaces
* @return the proxy object
*/
public synchronized LuaValueProxy getProxy(int index, Class<?>[] interfaces) {
check();
pushValue(index);
if (!isTable(index)) {
throw new IllegalArgumentException(String.format(
"index %d is not a table", index));
}
Class<?>[] allInterfaces = new Class<?>[interfaces.length + 1];
System.arraycopy(interfaces, 0, allInterfaces, 0, interfaces.length);
allInterfaces[allInterfaces.length - 1] = LuaValueProxy.class;
int reference = ref(REGISTRYINDEX);
try {
Object proxy = Proxy.newProxyInstance(classLoader, allInterfaces,
new LuaInvocationHandler(reference));
reference = -1;
return (LuaValueProxy) proxy;
} finally {
if (reference >= 0) {
unref(REGISTRYINDEX, reference);
}
}
}
// -- Private methods
/**
* Returns whether this Lua state is open.
*/
private boolean isOpenInternal() {
return luaState != 0L;
}
/**
* Closes this Lua state.
*/
private void closeInternal() {
if (isOpenInternal()) {
lua_close(ownState);
if (isOpenInternal()) {
throw new IllegalStateException("cannot close");
}
}
}
/**
* Checks this Lua state.
*/
private void check() {
// Check open
if (!isOpenInternal()) {
throw new IllegalStateException("Lua state is closed");
}
// Check proxy queue
LuaValueProxyRef luaValueProxyRef;
while ((luaValueProxyRef = (LuaValueProxyRef) proxyQueue.poll()) != null) {
proxySet.remove(luaValueProxyRef);
lua_unref(REGISTRYINDEX, luaValueProxyRef.getReference());
}
}
/**
* Creates a Lua runtime exception to indicate an argument type error.
*/
private LuaRuntimeException getArgTypeException(int index, LuaType type) {
return getArgException(index,
String.format("%s expected, got %s", type.toString()
.toLowerCase(), type(index).toString().toLowerCase()));
}
/**
* Creates a Lua runtime exception to indicate an argument error.
*
* @param extraMsg
* @return
*/
private LuaRuntimeException getArgException(int index, String extraMsg) {
check();
// Get execution point
String name = null, nameWhat = null;
LuaDebug luaDebug = lua_getstack(0);
if (luaDebug != null) {
lua_getinfo("n", luaDebug);
name = luaDebug.getName();
nameWhat = luaDebug.getNameWhat();
}
// Adjust for methods
if ("method".equals(nameWhat)) {
index--;
}
// Format message
String msg;
String argument = index > 0 ? String.format("argument #%d", index)
: "self argument";
if (name != null) {
msg = String
.format("bad %s to '%s' (%s)", argument, name, extraMsg);
} else {
msg = String.format("bad %s (%s)", argument, extraMsg);
}
return new LuaRuntimeException(msg);
}
// -- Native methods
private static native int lua_registryindex();
private static native String lua_version();
private native void lua_newstate(int apiversion, long luaState);
private native void lua_close(boolean ownState);
private native int lua_gc(int what, int data);
private native void lua_openlib(int lib);
private native void lua_load(InputStream inputStream, String chunkname,
String mode) throws IOException;
private native void lua_dump(OutputStream outputStream) throws IOException;
private native void lua_pcall(int nargs, int nresults);
private native void lua_getglobal(String name);
private native void lua_setglobal(String name);
private native void lua_pushboolean(int b);
private native void lua_pushbytearray(byte[] b);
private native void lua_pushinteger(int n);
private native void lua_pushjavafunction(JavaFunction f);
private native void lua_pushjavaobject(Object object);
private native void lua_pushnil();
private native void lua_pushnumber(double n);
private native void lua_pushstring(String s);
private native int lua_isboolean(int index);
private native int lua_iscfunction(int index);
private native int lua_isfunction(int index);
private native int lua_isjavafunction(int index);
private native int lua_isjavaobject(int index);
private native int lua_isnil(int index);
private native int lua_isnone(int index);
private native int lua_isnoneornil(int index);
private native int lua_isnumber(int index);
private native int lua_isstring(int index);
private native int lua_istable(int index);
private native int lua_isthread(int index);
private native int lua_compare(int index1, int index2, int operator);
private native int lua_rawequal(int index1, int index2);
private native int lua_rawlen(int index);
private native int lua_toboolean(int index);
private native byte[] lua_tobytearray(int index);
private native int lua_tointeger(int index);
private native Integer lua_tointegerx(int index);
private native JavaFunction lua_tojavafunction(int index);
private native Object lua_tojavaobject(int index);
private native double lua_tonumber(int index);
private native Double lua_tonumberx(int index);
private native long lua_topointer(int index);
private native String lua_tostring(int index);
private native int lua_type(int index);
private native int lua_absindex(int index);
private native int lua_arith(int operator);
private native void lua_concat(int n);
private native int lua_copy(int fromIndex, int toIndex);
private native int lua_gettop();
private native void lua_len(int index);
private native void lua_insert(int index);
private native void lua_pop(int n);
private native void lua_pushvalue(int index);
private native void lua_remove(int index);
private native void lua_replace(int index);
private native void lua_settop(int index);
private native void lua_createtable(int narr, int nrec);
private native int lua_getsubtable(int idx, String fname);
private native void lua_gettable(int index);
private native void lua_getfield(int index, String k);
private native void lua_newtable();
private native int lua_next(int index);
private native void lua_rawget(int index);
private native void lua_rawgeti(int index, int n);
private native void lua_rawset(int index);
private native void lua_rawseti(int index, int n);
private native void lua_settable(int index);
private native void lua_setfield(int index, String k);
private native int lua_getmetatable(int index);
private native void lua_setmetatable(int index);
private native int lua_getmetafield(int index, String k);
private native void lua_newthread();
private native int lua_resume(int index, int nargs);
private native int lua_status(int index);
private native int lua_ref(int index);
private native void lua_unref(int index, int ref);
private native LuaDebug lua_getstack(int level);
private native int lua_getinfo(String what, LuaDebug ar);
private native int lua_tablesize(int index);
private native void lua_tablemove(int index, int from, int to, int count);
// -- Enumerated types
/**
* Represents a Lua library.
*/
public enum Library {
/*
* The order of the libraries follows the definition in linit.c.
*/
/**
* The base library.
*/
BASE,
/**
* The package library.
*/
PACKAGE,
/**
* The coroutine library.
*
* @since JNLua 1.0.0
*/
COROUTINE,
/**
* The table library.
*/
TABLE,
/**
* The IO library.
*/
IO,
/**
* The OS library.
*/
OS,
/**
* The string library.
*/
STRING,
/**
* The bit32 library.
*
* @since JNLua 1.0.0
*/
BIT32,
/**
* The math library.
*/
MATH,
/**
* The debug library.
*/
DEBUG,
/**
* The Java library.
*/
JAVA {
@Override
void open(LuaState luaState) {
JavaModule.getInstance().open(luaState);
}
};
// -- Methods
/**
* Opens this library.
*/
void open(LuaState luaState) {
luaState.lua_openlib(ordinal());
}
}
/**
* Represents a Lua garbage collector action. Please see the Lua Reference
* Manual for an explanation of these actions.
*/
public enum GcAction {
/**
* Stop.
*/
STOP,
/**
* Restart.
*/
RESTART,
/**
* Collect.
*/
COLLECT,
/**
* Count memory in kilobytes.
*/
COUNT,
/**
* Count reminder in bytes.
*/
COUNTB,
/**
* Step.
*/
STEP,
/**
* Set pause.
*/
SETPAUSE,
/**
* Set step multiplier.
*/
SETSTEPMUL,
/**
* Undocumented.
*
* @since JNLua 1.0.0
*/
SETMAJORINC,
/**
* Returns whether the collector is running (i.e. not stopped).
*
* @since JNLua 1.0.0
*/
ISRUNNING,
/**
* Changes the collector to the generational mode.
*
* @since JNLua 1.0.0
*/
GEN,
/**
* Changes the collector to the incremental mode.
*
* @since JNLua 1.0.0
*/
INC
}
/**
* Represents a Lua arithmetic operator. Please see the Lua Reference Manual
* for an explanation of these operators.
*
* @since JNLua 1.0.0
*/
public enum ArithOperator {
/**
* Addition operator.
*/
ADD,
/**
* Subtraction operator.
*/
SUB,
/**
* Multiplication operator.
*/
MUL,
/**
* Division operator.
*/
DIV,
/**
* Modulo operator.
*/
MOD,
/**
* Exponentiation operator.
*/
POW,
/**
* Mathematical negation operator.
*/
UNM
}
/**
* Represents a Lua relational operator. Please see the Lua Reference Manual
* for an explanation of these operators.
*
* @since JNLua 1.0.0
*/
public enum RelOperator {
/**
* Equality operator.
*/
EQ,
/**
* Less than operator.
*/
LT,
/**
* Less or equal operator.
*/
LE
}
// -- Nested types
/**
* Phantom reference to a Lua value proxy for pre-mortem cleanup.
*/
private static class LuaValueProxyRef extends
PhantomReference<LuaValueProxyImpl> {
// -- State
private int reference;
// --Construction
/**
* Creates a new instance.
*/
public LuaValueProxyRef(LuaValueProxyImpl luaProxyImpl, int reference) {
super(luaProxyImpl, luaProxyImpl.getLuaState().proxyQueue);
this.reference = reference;
}
// -- Properties
/**
* Returns the reference.
*/
public int getReference() {
return reference;
}
}
/**
* Lua value proxy implementation.
*/
private class LuaValueProxyImpl implements LuaValueProxy {
// -- State
private int reference;
// -- Construction
/**
* Creates a new instance.
*/
public LuaValueProxyImpl(int reference) {
this.reference = reference;
proxySet.add(new LuaValueProxyRef(this, reference));
}
// -- LuaProxy methods
@Override
public LuaState getLuaState() {
return LuaState.this;
}
@Override
public void pushValue() {
synchronized (LuaState.this) {
rawGet(REGISTRYINDEX, reference);
}
}
}
/**
* Invocation handler for implementing Java interfaces in Lua.
*/
private class LuaInvocationHandler extends LuaValueProxyImpl implements
InvocationHandler {
// -- Construction
/**
* Creates a new instance.
*/
public LuaInvocationHandler(int reference) {
super(reference);
}
// -- InvocationHandler methods
@Override
public Object invoke(Object proxy, Method method, Object[] args)
throws Throwable {
// Handle LuaProxy methods
if (method.getDeclaringClass() == LuaValueProxy.class) {
return method.invoke(this, args);
}
// Handle Lua calls
synchronized (LuaState.this) {
pushValue();
getField(-1, method.getName());
if (!isFunction(-1)) {
pop(2);
throw new UnsupportedOperationException(method.getName());
}
insert(-2);
int argCount = args != null ? args.length : 0;
for (int i = 0; i < argCount; i++) {
pushJavaObject(args[i]);
}
int retCount = method.getReturnType() != Void.TYPE ? 1 : 0;
call(argCount + 1, retCount);
try {
return retCount == 1 ? LuaState.this.toJavaObject(-1,
method.getReturnType()) : null;
} finally {
if (retCount == 1) {
pop(1);
}
}
}
}
}
/**
* Lua debug structure.
*/
private static class LuaDebug {
/**
* The <code>lua_Debug</code> pointer on the JNI side. <code>0</code>
* implies that the activation record has been freed. The field is
* modified exclusively on the JNI side and must not be touched on the
* Java side.
*/
private long luaDebug;
/**
* Ensures proper finalization of this Lua debug structure.
*/
private Object finalizeGuardian;
/**
* Creates a new instance.
*/
private LuaDebug(long luaDebug, boolean ownDebug) {
this.luaDebug = luaDebug;
if (ownDebug) {
finalizeGuardian = new Object() {
@Override
public void finalize() {
synchronized (LuaDebug.this) {
lua_debugfree();
}
}
};
}
}
// -- Properties
/**
* Returns a reasonable name for the function given by this activation
* record, or <code>null</code> if none is found.
*/
public String getName() {
return lua_debugname();
}
/**
* Explains the name of the function given by this activation record.
*/
public String getNameWhat() {
return lua_debugnamewhat();
}
// -- Native methods
private native void lua_debugfree();
private native String lua_debugname();
private native String lua_debugnamewhat();
}
}