# luars
[](../../LICENSE)
[](https://crates.io/crates/luars)
luars is an embeddable pure Rust Lua 5.5 runtime crate. It includes the compiler, VM, GC, standard library, and a high-level host API built around `Lua`.
If you want the repository-level overview, including examples and companion crates, start with [../../README.md](../../README.md). This README focuses on the crate surface that application code should use directly.
## Installation
```toml
[dependencies]
luars = "0.18"
```
Optional features:
```toml
[dependencies]
luars = { version = "0.18", features = ["serde", "sandbox"] }
```
## Quick Start
```rust
use luars::{Lua, SafeOption, Stdlib};
fn main() -> Result<(), Box<dyn std::error::Error>> {
let mut lua = Lua::new(SafeOption::default());
lua.load_stdlibs(Stdlib::All)?;
lua.register_function("add", |a: i64, b: i64| a + b)?;
let sum: i64 = lua.load("return add(1, 2)").eval()?;
assert_eq!(sum, 3);
Ok(())
}
```
## High-Level Workflow
### Execute code
```rust
lua.load("x = 40 + 2").exec()?;
let answer: i64 = lua.load("return x").eval()?;
let pair: (i64, i64) = lua.load("return 20, 22").eval_multi()?;
```
### Call Lua globals
```rust
lua.load(
r#"
function greet(name)
return "hello, " .. name
end
"#,
)
.exec()?;
let text: String = lua.call_global1("greet", "luars")?;
```
### Register Rust functions
```rust
lua.register_function("slugify", |value: String| {
value.trim().to_lowercase().replace(' ', "-")
})?;
```
### Exchange tables and globals
```rust
let config = lua.create_table_from([("host", "127.0.0.1"), ("mode", "dev")])?;
lua.globals().set("config", config)?;
let globals = lua.globals();
let host: String = globals.get("config")?.get("host")?;
assert_eq!(host, "127.0.0.1");
```
### Expose Rust types as userdata
```rust
use luars::{LuaUserData, lua_methods};
#[derive(LuaUserData)]
struct Counter {
pub value: i64,
}
#[lua_methods]
impl Counter {
pub fn new(value: i64) -> Self {
Self { value }
}
pub fn inc(&mut self, delta: i64) {
self.value += delta;
}
pub fn get(&self) -> i64 {
self.value
}
}
lua.register_type::<Counter>("Counter")?;
let count: i64 = lua
.load(
r#"
local counter = Counter.new(1)
counter:inc(41)
return counter:get()
"#,
)
.eval()?;
assert_eq!(count, 42);
```
### Use scoped borrowed values
```rust
let format_name = scope.create_function_with(&prefix, |prefix: &String, value: String| {
format!("{prefix}{value}")
})?;
scope.globals().set("format_name", &format_name)?;
scope.load("return format_name('alice')").eval()
})?;
assert_eq!(result, "user:alice");
```
## Async And Sandbox
The high-level API supports both typed async callbacks and async execution entry points:
```rust
lua.register_async_function("double_async", |value: i64| async move {
Ok(value * 2)
})?;
let result: i64 = lua.load("return double_async(21)").eval_async().await?;
assert_eq!(result, 42);
```
You can also drive existing Lua functions asynchronously with `call_async()`, `call_async1()`, `call_async_global()`, and `call_async_global1()`.
When the `sandbox` feature is enabled, the same high-level surface exposes isolated execution helpers:
```rust
use luars::SandboxConfig;
let mut sandbox = SandboxConfig::default();
lua.sandbox_insert_global(&mut sandbox, "answer", 42_i64)?;
let answer: i64 = lua.eval_sandboxed("return answer", &sandbox)?;
assert_eq!(answer, 42);
```
For more detail, see [../../docs/Async.md](../../docs/Async.md).
## Feature Flags
| `serde` | Enable serde-based conversions |
| `sandbox` | Enable sandbox execution helpers |
| `shared-proto` | Enable shared prototypes for multi-VM scenarios |
## Known Boundaries
- No C API and no direct loading of native C Lua modules
- `string.dump` produces luars-specific bytecode
- Some corners of `debug`, `io`, and `package` still differ from the official C Lua implementation
See [../../docs/Different.md](../../docs/Different.md) for the detailed compatibility notes.
## Documentation
| [../../docs/Guide.md](../../docs/Guide.md) | High-level embedding guide |
| [../../docs/UserGuide.md](../../docs/UserGuide.md) | High-level userdata guide |
| [../../docs/Async.md](../../docs/Async.md) | High-level async and sandbox guide |
| [../../docs/Different.md](../../docs/Different.md) | Known differences from C Lua |
## License
MIT. See [../../LICENSE](../../LICENSE).