Android-Lua

Based on Androlua for Lua5.3.3, make some practical changes.

blog: https://www.jianshu.com/p/908a1ac893bb

依赖 Dependency

implementation "me.chenhe:android-lua:1.1.1"

⚠️ 由于 JCenter 停止维护，本 lib 已经传至 maven central，坐标变更为 me.chenhe:android-lua。

Because JCenter is read only now, this lib has published to maven central. But the coordinate changed to me.chenhe:android-lua.

混淆 ProGuard

如果你使用R8（Gradle 3.4.0　默认使用）则无需添加任何规则。否则请添加下述内容：

If you use R8 which is default in Gradle 3.4.0 nothing need to do. Else add the rules below:

-keep class org.keplerproject.luajava.**{ *; }

DEMO

Demo 工程位于源码的 app module 下，里面演示了下面讲述的所有基础应用。

使用 Usage

初始化

Lua 与 C 依靠一个虚拟的栈来完成数据交换。包括变量、函数、参数、返回值等在内的一切数据，都要放入栈中来共享。为了调用方便，这个栈并不是严格遵循栈的规则。从索引来看，栈底索引为1，往上依次递增。而栈顶索引是-1，往下依次递减。因此，正负索引都是合法的，但是0不可以。下面是栈的示意图：

所以要在 java 中使用 Lua，首先我们需要创建一个 Lua 运行环境，也就是 Lua 栈：

LuaState lua = LuaStateFactory.newLuaState(); //创建栈
lua.openLibs(); //加载标准库

lua.close(); //养成良好习惯，在执行完毕后销毁Lua栈。

这样我们就创建了一个 Lua 运行时。每一个 LuaState 实例都是一个独立的运行时，你可以创建多个运行时，他们相互隔离。

任何时候都可以使用 Log.i("LuaStack", lua.dumpStack()); 或通过其他你喜欢的输出方式查看 lua 栈的当前情况，以免更好地理解 c 与 Lua 的交互过程。

加载 Lua 脚本

使用 lua.LdoString() 可以轻松执行一段 Lua 代码。通过其返回值可以判断执行是否成功。0 表示成功否则表示不成功。若不成功则错误信息会直接入栈，我们可以通过 lua.toString(-1) 获取到。

同时也提供了 lua.LdoFile() 来直接执行 Lua 源码文件，但请注意这里只允许传入本地文件路径且具有访问权限。

LdoFile() 支持加载 Lua 编译后的字节码。但请注意 Lua 原生字节码不是完全跨平台，例如32与64位就不兼容。如果有这方面需求请考虑 Lua JIT。

这里 API 没有采用标准的小驼峰规范，是因为直接原样保留了 Lua 的 C API 函数名，便于与 Lua 官方文档对照。

获取 Lua 变量

首页要说明的是，只有全局变量（非 local）才可以读取。

lua:

v1 = "this is value from lua"

java:

lua.getGlobal("v1"); // 请求 v1 变量的值，入栈
String s = lua.toString(-1) // 从栈中取得了值
lua.pop(1); // 及时将不用的数据出栈避免栈溢出
// 此时 s = "this is value from lua"

记住，lua.toXXX() 函数在取得值之后是不会自动出栈的。记得手动弹出以免栈溢出。lua.pop() 可以从栈顶弹出指定个数的元素。

注入 Lua 变量

有时我们需要在 android 中创建 Lua 变量，这样就可以在 Lua 中直接使用了。注意，这里创建的变量都是全局的（非 local）。

java:

lua.pushString( "from java" ); //压入欲注入变量的值
lua.setGlobal("v2"); // 设置变量名
// 现在可以在 lua 脚本中使用 `v2` 变量了。

首先通过 lua.pushXxx() 将值入栈，然后使用 lua.setGlobal() 传递一个变量名即可。它会自动把栈顶元素弹出作为变量的值。因此这两个操作完成后栈是空的（假设没有其他元素），不需要单独 pop.

如果注入的变量名已经存在则会覆盖原先的值。

遍历 Lua 表（数组）

Lua 的表相对来说是特别灵活的，既可以作为数组，也可以作为键值数组。而且同一个 table 里，key 与 value 的数据类型都可以不同。但无论如何，在 java 中的遍历方式都是一样的。

lua:

-- 以键值数组为例
table = {}
table["name"] = "Lily"
table["age"] = 18
table["sex"] = "female"

java:

lua.getGlobal( "table" );
StringBuilder s = new StringBuilder();
if ( lua.isTable( -1 ) )
{
	lua.pushNil(); // 压入一个空值作为初始 key 启动遍历
	while ( lua.next( -2 ) != 0 )
	{
		s.append( lua.toString( -2 ) ).append( " = " )
		.append( lua.toString( -1 ) ).append( "\n" );
		lua.pop( 1 );
	}
	lua.pop( 1 ); // 弹出 table 本身
}
// 最后 StringBuilder 里的内容是：name = Lily\nage=18\nsex=female
// 顺序可能错乱，因为 k-v 不一定是有序的。

类似之前，首先找到了 table 变量并入栈。随后通过 lua.isTable() 判断指定位置的元素是不是一个 table。-1 表示栈顶，也就是刚刚入栈的变量。

lua.next() 接受一个参数指明要遍历的 table 在栈中的位置，由于我们先 push 了一个 Nil，因此这里是-2。这个函数会弹出栈顶元素作为 key，将下一对 k-v 依次入栈，若没有下一个元素返回0。因此在执行完 next() 后栈中最顶上两个元素依次为 value、key。

取出所需数据后我们将 value 弹出，保留 key 进行下一次 next() 完成遍历，最后别忘记弹出 table 本身。

注入 Lua 表

类似注入普通变量。

java:

lua.newTable(); // 新建一个table，并压入栈。
lua.pushString( "from" );
lua.pushString( "java" );
lua.setTable( -3 ); // 设置一个元素
lua.pushString( "value" );
lua.pushString( "Hello lua" );
lua.setTable( -3 );
lua.setGlobal( "table" );

首先需要创建一个 table。接着将 key、value 依次入栈，随后调用 lua.setTable() 设置一个元素。它接受一个参数指明要设置的 table 在栈中的位置。因为我们已经压入了两个值，因此 table 的位置是-3。它会弹出栈顶的两个值分别作为 value、key。最后使用 lua.setGlobal() 弹出 table 本身并注入为变量。

上面代码运行后，等价于下面的 Lua table 定义：

table = {}
table["from"] = "java"
table["value"] = "Hello lua"

Java 调用 Lua 函数

你可以将 Lua 函数理解为一个特殊的变量。因此要调用 Lua 函数，首先要像获取 Lua 变量那样获取它。

lua:

-- 这是一个获取最大值与最小值的函数
-- Lua 允许多个返回值，其实这是一个语法糖，内部使用的是 table 包装
function extreme(a, b, c)
    local max = a
    local min = a
    if(b>max) then
        max = b
    elseif(b<min) then
        min = b
    end
    if(c>max) then
        max = c
    elseif(c<min) then
        min = c
    end
    return max, min
end

java:

StringBuilder s = new StringBuilder();
lua.getGlobal("extreme"); // 获取到函数入栈
lua.pushNumber(15.6); // 依次压入三个参数
lua.pushNumber(0.8);
lua.pushNumber(189);
lua.pcall(3, 2, 0); // 调用函数
s.append("max:").append(lua.toString(-2)).append(" min:").append(lua.toString(-1));
// 最后 StringBuilder 里的内容是：max:189 min:0.8

lua.pcall() 接受三个参数，依次是函数的参数个数、返回值的个数、错误处理函数索引。它将把栈顶的 n 个元素作为参数出栈，把第 n+1 个元素作为要调用的函数本身出栈，进行调用后将返回值依次入栈。

类似 lua.LdoString()，可以通过返回值判断是否执行成功，也可以直接从栈中拿到错误信息。

错误处理函数索引 指的是当函数发生错误时，将会自动调用一个处理错误的函数。这个函数必须提前入栈，并在这里传入它在栈中的索引。

Lua 调用 Java 函数

Lua 调用 java 函数相对复杂，毕竟 java 不是脚本语言。我们需要将 java 函数包装成一个 JavaFunction 类，实例化之后注册到 Lua，这样才可以从 Lua 调用。下面看一个例子：

public class MyJavaFunction extends JavaFunction {
    public MyJavaFunction(LuaState luaState) {
        super(luaState);
    }
    @Override
    public int execute() {
        // 获取Lua传入的参数，注意第一个参数固定为上下文环境。
        String str = L.toString(2);

        SimpleDateFormat simpleDateFormat = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss");
        Date date = new Date(System.currentTimeMillis());
        L.pushString(simpleDateFormat.format(date) + str);
        return 1; // 返回值的个数
    }

    public void register() {
        try {
            // 注册为 Lua 全局函数
            register("getTime");
        } catch (LuaException e) {
            e.printStackTrace();
        }
    }
}

new MyJavaFunction(lua).register();
// 现在我们可以在 lua 中直接调用 `getTime(" -suffix")`，
// 得到的返回值类似 2019-06-01 23:56:49 -suffix

我们创建一个类继承 JavaFunction 并实现 execute() 方法，它将在被 Lua 调用时执行。前面说过，Lua 与 c 靠栈来交换数据，故调用函数所传的参数也会入栈。需要注意的是第一个元素恒为 Lua 的上下文环境，实际传入的参数索引是从2开始。在这个简单的例子中，我们取得了 Lua 传递的字符串，并将其拼接在由 java 获取的时间字符串后边一起返回给 Lua。

与传参类似，返回值也是直接入栈即可。最后我们需要返回返回值的个数，这样 Lua 就知道从栈里取出几个元素作为返回值了。这些元素会被自动出栈。这里我们利用 L.pushString() 将拼接后的字符串返回给 Lua，并返回 1 表示有1个返回值。

最后实例化刚才包装的类就可以成功注册了。现在我们可以在 Lua 中调用 getTime(String)，它将返回一个字符串，内容是当前的时间加上我们传入的字符串。

Lua 语言是为嵌入而生的，因此他的标准库小的可怜，甚至没有获取当前时间的函数，更别提网络访问了。因此实际项目中我们会根据项目需要大量注册 java 函数供 Lua 使用。

为了方便管理，我们可以将函数作为元素注册到 table 里，最后将 table 注入 Lua，这样在 Lua 中可以使用类似 System.getTime() 的形式调用。

注入 java 对象

除了注入简单的 java 函数，甚至可以直接注入一个 java 对象，这样这个对象所拥有的所有成员都可以在 Lua 中直接使用。

java:

TextView textView = findViewById(R.id.textView);
lua.pushJavaObject(textView);
lua.setGlobal("textView");
lua.pushInteger(Color.RED);
lua.setGlobal("red");
// 现在可以直接在 Lua 中调用 `textView:setTextColor(red)` 来将文本框设置为红色
// setTextColor() 是 TextView 的成员函数，我们没有显式注入但可以直接使用。
// 类似的，setTextSize() 也可以直接使用。

使用 lua.pushJavaObject() 可以非常轻松地注入 java 对象作为 Lua 变量。注意，在 Lua 中调用对象的成员函数需要使用冒号 :，这其实也是一个语法糖，textView:setTextColor(red) 等价于 textView.setTextColor(self, red)，也就是说冒号自动地传递了 self 参数来模拟面向对象。

警告： 由于注册对象会自动注册其所有成员函数与变量，因此开销是非常大的。请谨慎使用这一特性。

Lua 回调（HTTP 请求）

前面讲了 Lua 调用 java 函数并可以取得返回值，这是在单线程情况下的。如果 java 需要异步执行一个耗时的操作（例如 HTTP 请求），那么就需要 Lua 提供一个回调函数。Lua 是支持闭合函数（closure）的，因此回调要比 java 定义一个接口简单不少。下面看一个例子：

java:

// 简单起见省略了一些代码和必要的 try-catch
public class AsyncJavaFunction extends JavaFunction {
    // lua 回调函数
    private LuaObject callbackFun;

    @Override
    public int execute() {
        if (L.isFunction(2)) {
            callbackFun = L.getLuaObject(2); // 获取回调
            new MyAsync().execute();
        }
        return 0;
    }

    private class MyAsync extends AsyncTask<Integer, Integer, Integer> {
        long t;
        @Override
        protected void onPreExecute() {
            super.onPreExecute();
            t = System.currentTimeMillis();
        }
        @Override
        protected Integer doInBackground(Integer... integers) {
            Thread.sleep(2000);  // 模拟耗时操作（例如网络请求）
            return null;
        }
        @Override
        protected void onPostExecute(Integer integer) {
            super.onPostExecute(integer);
            if (callbackFun != null)
               callbackFun.call(new Object[]{"OK", System.currentTimeMillis() - t}, 0);
        }
    }
}

lua:

http(function(result, time)
        r = string.format("result: %s\ntime: %dms", result, time)
    end
)
-- 最后r的结果可能是：result: OK \n time: 2231ms

类似前面的，首先我们需要向 Lua 注入一个 java 函数并取得 Lua 传入的参数。只不过这一次有一个参数是 Function 类型的，它可以直接使用成员函数 call() 来执行，在 Lua 中表现为传入一个闭包函数作为参数。

当 java 异步任务执行完毕后，通过 call() 通知回调，传入一个 Object 数组作为参数，这里有2个成员，分别是结果与耗时。0 表示回调函数没有返回值，如果有会直接入栈，利用 lua.toXXX() 取出就行了。

提示：

这里采用的是闭包回调。其实还可以使用全局函数作为回调。

只需要在 Lua 中定义好一个全局函数，然后直接把函数名(String)作为参数传给 java 即可。通过前面 Java 调用 Lua 函数 章节所讲的方法就可以执行这个“回调”了。

这两种方式各有优点。前者代码条理更加清晰，后者比较适合复杂且重复使用的回调。

更多高级用法

基础用法基本上讲完了，其实所谓的高级用法都是由基础用法拼接来的。尤其是 table，这在 Lua 中是一个非常强大与灵活的东西。以及 metatable 更是如此。如果想掌握高级应用，还得深入了解 Lua 本身的原理，这里就不再赘述了。

这个 README 只是抛砖引玉，帮助各位快速在 Android 上整合 Lua，更加深入的问题还请自行查阅 Lua API 文档或其他资料。

链接

Android-LuaJIT

赞助

本项目 CDN 加速及安全防护由 Tencent EdgeOne 赞助

亚洲最佳CDN、边缘和安全解决方案 - Tencent EdgeOne

License

ichenhe/Android-Lua

ErrorLooks like something went wrong!

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Error
Looks like something went wrong!

Packages