Kahlua Java-based Lua Virtual Machine

Kahlua is a Lua-compatible Virtual Machine and standard library implemented entirely in Java. It is designed to emulate Lua behavior by reverse-engineering Lua features (using the Lua reference manual and PiL as guides) rather than direct porting.

Key characteristics:

• Target Platform: Optimized for J2ME (CLDC 1.1), making it suitable for mobile environments, but also compatible with standard Java (J2SE/J2EE).
• Integration: Designed for easy integration into J2ME projects. For J2SE/J2EE environments, note that Kahlua lacks a built-in Lua compiler, so a standalone Lua compiler must be used.
• Goals: Focuses on a small class file footprint, fast runtime for common operations, and high test coverage while maintaining Lua-standard behavior.

Kahlua maps fundamental Lua types to Java types as follows:

In recent versions of Kahlua, strings are no longer interned everywhere to prevent PermGen heap exhaustion (especially critical on J2ME devices) and to simplify the Java API.

When working with Kahlua, you must follow these rules:

1. Do not assume identity equality: Do not assume that strings coming from Lua are interned. You cannot rely on == (identity comparison) for string equality; use standard string equality methods instead.
2. Avoid manual interning: Do not manually intern strings that you are sending to Lua.

Kahlua does not use the standard Lua userdata concept. Instead, you can pass any Java object directly into Kahlua.

To operate on these objects, you must set the metatable for the specific class. Note that this applies to all objects of that exact class, but does not automatically apply to subclasses. The recommended way to manipulate these objects is to export Java functions that can operate on them.

Kahlua uses Apache Ant for its build process. To compile, package, and run all test cases, execute the ant command from the project root.

After building, you can find:

• A test report at testreport.html.
• A coverage report at testsuite/coverage/coverage.html.

Unlike standard Lua which requires a stack-based API (like lua_gettable), Kahlua allows you to interact with Lua objects directly using Java objects. You primarily need LuaState.getEnvironment() to access the global scope.

To get a value from a Lua table:

1. Get the environment from the LuaState.
2. Use rawget(key) on the LuaTable to retrieve the object.
3. Use instanceof to check the type and cast to the appropriate Java type (e.g., Boolean, Double, String).

LuaState state = myState;
// Access a global table
LuaTable table = (LuaTable) state.getEnvironment().rawget("myTable");

// Access a key within that table
Object value = table.rawget("myKey");

if (value instanceof Boolean) {
    boolean boolVal = (Boolean) value;
}

In Kahlua, environments are stored per LuaThread rather than per LuaState.

To access the environment of the current thread, do not attempt to access LuaState.environment directly (as it is no longer available). Instead, use the convenience method LuaState.getEnvironment(), which retrieves the environment associated with the current thread.

Kahlua provides debugstacktrace(thread, level, count, halt_at) as an alternative to Lua's debug.traceback.

• thread: The thread to inspect (nil for current thread).
• level: Integer >= 0. The stack level to start at (0 is debugstacktrace itself, 1 is the caller). Defaults to 0.
• count: Integer representing the upper limit of stackframes to return. Defaults to all.
• halt_at: Integer representing the stack height at which to stop. Defaults to 0.

Kahlua's collectgarbage([opt]) is tied to Java's garbage collection. Supported options are:

• null, "step", or "collect": Runs System.gc() in Java (behavior is not guaranteed).
• "count": Returns three values: usedMemory, freeMemory, and totalMemory (all in KB).

All other values for opt will result in an error. Note that __gc metatable modes and standard Lua collectgarbage options are not supported.

In Kahlua, pcall returns additional information on failure compared to standard Lua.

Standard Lua returns:

• false, errormessage

Kahlua returns:

1. false
2. errormessage
3. stacktrace (a string with newlines separating each call frame)
4. The original Java exception