Java API

The Java API is mostly designed around the party.iroiro.luajava.Lua interface and the party.iroiro.luajava.value.LuaValue interface.

To start, simply acquire a Lua state with any of the following constructors:

• new Lua51()
• new Lua52()
• new Lua53()
• new Lua54()
• new LuaJit()
• new LuaJ()

Close the state

Just like the C API, you will need to close the state after you are done with it:

Lua L = new Lua51();
// Operations
L.close();

// Or
try (Lua J = new Lua51()) {
    // Operations
}

WARNING

Currently the sub-threads (created with mainState.newThread()) are only cleaned up after you close the main state. This shouldn't be a problem unless you have millions of sub-threads.

Open libraries

By default, the Lua state is only loaded with the java library. To use Lua libraries like string, table or coroutine, you will need to explicitly open the libraries:

• openLibraries: Opens all available libraries.

• openLibrary: Opens a specific library.

Interact with Lua values

To interact with Lua values, you can use the LuaValue interface or make use of the Lua C API bindings directly.

LuaValue interface

The party.iroiro.luajava.value.LuaValue interface is a wrapper around a Lua value. Internally, for complex values (for example, Lua tables), it uses references to refer to the Lua value, garbage collected after the LuaValue instance becomes a phantom reference.

try (Lua L = new Lua54()) {
    LuaValue[] returnValues = L.eval("return { a = 1 }, 1024, 'my string value'");
    assertEquals(3, returnValues.length);
    assertEquals(1, returnValues[0].get("a").toInteger());
    assertEquals(1024, returnValues[1].toInteger());
    assertEquals("my string value", returnValues[2].toString());
}

The JavaDoc of LuaValue should be quite self-explanatory. The following texts list several commonly used patterns to help you get familiar with the API.

Get global variables

Every Lua state implementation implements the LuaThread interface, providing a convenient way to retrieve and use LuaValues:

To obtain a LuaValue from a Lua global variable, use Lua::get(String):

try (Lua L = new Lua54()) {
    assertEquals("Lua 5.4", L.get("_VERSION").toString());
}

Set global variables

To set a Lua global variable to any LuaValue or any arbitrary Java object, use Lua::set(String, Object):

try (Lua L = new Lua54()) {
    LuaValue value = L.from(1);
    L.set("a", value); // LuaValue
    L.set("b", 2); // Java Integer
    L.set("c", new BigDecimal(3)); // Any Java object
    assertEquals(
    6,
    L.eval("return a + b + c:longValue()")[0].toInteger()
    );
}

LuaValues from Java values

To create a LuaValue from a simple Java value, use Lua::from(boolean/double/long/String) or Lua::fromNull().

try (Lua L = new Lua54()) {
    LuaValue value = L.from(1);
    L.set("a", value); // LuaValue
    L.set("b", 2); // Java Integer
    L.set("c", new BigDecimal(3)); // Any Java object
    assertEquals(
    6,
    L.eval("return a + b + c:longValue()")[0].toInteger()
    );
}

LuaValues from Lua evaluation

To run Lua code and obtain the returned values, use Lua::eval(String):

try (Lua L = new Lua54()) {
    L.openLibraries();
    LuaValue[] values1 = L.eval("string.sub('abcdefg', 0, 3)");
    assertEquals(0, values1.length);
    LuaValue[] values2 = L.eval("return string.sub('abcdefg', 0, 3)");
    assertEquals("abc", values2[0].toString());
}

TIP

With Lua::eval, you will need an explicit Lua return statement to have Lua::eval return the values.

Manipulate Lua tables

LuaValues implements the Java Map interface and allow direct manipulation of Lua tables.

try (Lua L = new Lua54()) {
    L.run("t = { text = 'abc', children = { 'a', 'b', 'c' } }");
    LuaValue table = L.eval("return t")[0];
    // Get-calls return LuaValues.
    assertEquals("abc", table.get("text").toString());
    LuaValue children = table.get("children");
    // Indices are 1-based.
    assertEquals("a", children.get(1).toString());
    assertEquals(3, children.size());
    // Set-calls accept LuaValues or any Java object.
    children.set(4, "d");
    // Changes are done in the Lua side.
    L.run("assert(t.children[4] == 'd')");
}

Call Lua functions

Use LuaValue::call(...) to call a function LuaValue and receive its return values as LuaValues:

try (Lua L = new Lua54()) {
    L.openLibrary("string");
    LuaValue gsub = L.eval("return string.gsub")[0];
    LuaValue luaJava = gsub.call("Lua", "a", "aJava")[0];
    assertEquals("LuaJava", luaJava.toString());
}

Create Java proxies

Create proxies with LuaValue::toProxy:

try (Lua L = new Lua54()) {
    LuaValue runnable = L.eval("return { run = function() print('running...') end }")[0];
    Runnable r = runnable.toProxy(Runnable.class);
    Thread t = new Thread(r);
    t.start();
    t.join();
}