Ergonomic, efficient and Zero-cost rust bindings to Lua5.4
First, add ezlua to your dependencies in Cargo.toml
toml
[dependencies]
ezlua = { version = '0.2' }
Then, use ezlua in rust, the code framework like this ```rust use ezlua::prelude::*;
fn main() -> LuaResult<()> { // create a lua VM let lua = Lua::withopenlibs();
// load your lua script and execute it
lua.do_string(r#"function add(a, b) return a + b end"#, None)?;
// get function named add from lua global table
let add = lua.global().get("add")?;
// call add function and get its result
let result = add.pcall::<_, u32>((111, 222))?;
assert_eq!(result, 333);
// ... for the following code
Ok(())
} ```
Of course, you can provide your rust function to lua via ezlua binding, and it's very simple, like this
rust
lua.global().set("add", lua.new_closure(|a: u32, b: u32| a + b)?)?;
lua.do_string("assert(add(111, 222) == 333)", None)?;
And you can bind exists function easily ```rust let string: LuaTable = lua.global().get("string")?.tryinto()?; string.setclosure("trim", str::trim)?; string.setclosure("trimstart", str::trimstart)?; string.setclosure("trimend", str::trimend)?;
let os: LuaTable = lua.global().get("os")?.tryinto()?; os.setclosure("mkdir", std::fs::createdir::<&str>)?; os.setclosure("mkdirs", std::fs::createdirall::<&str>)?; os.setclosure("rmdir", std::fs::removedir::<&str>)?; os.setclosure("chdir", std::env::setcurrentdir::<&str>)?; os.setclosure("getcwd", std::env::currentdir)?; os.setclosure("getexe", std::env::current_exe)?; ```
Implement ToLua trait for your type, and then you can pass it to lua
```rust
struct Config { name: String, path: String, timeout: u64, // ... }
impl ToLua for Config {
fn tolua<'a>(self, lua: &'a LuaState) -> LuaResult
lua.global().setclosure("defaultconfig", Config::default)?; ```
Continuing with the example above, you can simply the binding code via serde
```rust use serde::{Deserialize, Serialize}; use ezlua::serde::SerdeValue;
struct Config { name: String, path: String, timeout: u64, // ... }
impl ToLua for Config {
fn tolua<'a>(self, lua: &'a LuaState) -> LuaResult
impl FromLua<'> for Config {
fn fromlua(lua: &LuaState, val: ValRef) -> Option
lua.global().set("DEFAULTCONFIG", SerdeValue(Config::default()))?; lua.global() .setclosure("set_config", |config: Config| { // ... set your config })?; ```
ezlua's userdata binding mechanism is powerful, the following code comes from std bindings
```rust use std::{fs::Metadata, path::*};
impl UserData for Metadata {
fn getter(fields: UserdataRegistry
Ok(())
}
fn methods(mt: UserdataRegistry<Self>) -> Result<()> {
mt.set_closure("len", Self::len)?;
mt.set_closure("is_dir", Self::is_dir)?;
mt.set_closure("is_file", Self::is_file)?;
mt.set_closure("is_symlink", Self::is_symlink)?;
Ok(())
}
} ```
Types impls the UserData trait, ezlua also impls ToLua for itself, and impls FromLua for its reference
rust
lua.global().set("path_metadata", Path::metadata)?;
Defaultly, types binded as userdata is immutable, if you need mutable reference, you can specific a UserData::Trans type, and there is a builtin impl that is RefCell, so the mutable binding impls looks like this
```rust
use core::cell::RefCell;
use std::process::{Child, Command, ExitStatus, Stdio};
impl UserData for Child {
type Trans = RefCell
fn getter(fields: UserdataRegistry<Self>) -> LuaResult<()> {
fields.add("id", Self::id)?;
Ok(())
}
fn methods(mt: UserdataRegistry<Self>) -> Result<()> {
mt.add_mut("kill", Self::kill)?;
mt.add_mut("wait", Self::wait)?;
mt.add_mut("try_wait", |this: &mut Self| {
this.try_wait().ok().flatten().ok_or(())
})?;
}
} ```
To register a lua module, you can provide a rust function return a lua table via LuaState::register_module method
```rust
lua.registermodule("json", ezlua::binding::json::open, false)?;
lua.registermodule("path", |lua| {
let t = lua.new_table()?;
t.set_closure("dirname", Path::parent)?;
t.set_closure("exists", Path::exists)?;
t.set_closure("abspath", std::fs::canonicalize::<&str>)?;
t.set_closure("isabs", Path::is_absolute)?;
t.set_closure("isdir", Path::is_dir)?;
t.set_closure("isfile", Path::is_file)?;
t.set_closure("issymlink", Path::is_symlink)?;
return Ok(t);
}, false)?; ```
And then use them in lua ```lua local json = require 'json' local path = require 'path'
local dir = path.abspath('.') assert(json.load(json.dump(dir)) == dir) ```
To use multiple thread feature in lua, you need to specify the thread feature in Cargo.toml, and patch the lua-src crate with ezlua's custom
```toml
[dependencies]
ezlua = { version = '0.2', features = ['thread'] }
[patch.crates-io] lua-src = { git = "https://github.com/metaworm/lua-src-rs" } ```
And then, register the thread module for lua
rust
lua.register_module("thread", ezlua::binding::std::thread::init, true)?;
And then, use it in lua ```lua local thread = require 'thread' local threads = {} local tt = { n = 0 } local count = 64 for i = 1, count do threads[i] = thread.spawn(function() tt.n = tt.n + 1 -- print(tt.n) end) end
for i, t in ipairs(threads) do t:join() print('#' .. i .. ' finished') end assert(tt.n == count) ```
In addition, you can also start a new thread with the same lua VM ```rust let co = Coroutine::empty(&lua); std::thread::spawn(move || { let print = co.global().get("print")?; print.pcall_void("running lua in another thread")?;
LuaResult::Ok(())
}) .join() .unwrap(); ```
TODO