Crate mlua_batteries

Expand description

Batteries-included standard library modules for mlua.

Each module exposes a single module(lua) -> LuaResult<LuaTable> entry point. Register individually or use register_all for convenience.

§Platform support

This crate targets Unix server platforms (Linux, macOS). Windows is not a supported target.

§Encoding — UTF-8 only (by design)

All path arguments are received as Rust String (UTF-8). Non-UTF-8 Lua strings are rejected at the FromLua boundary. Returned paths use to_string_lossy, replacing any non-UTF-8 bytes with U+FFFD.

§Why not raw bytes / `OsStr`?

mlua’s FromLua for String performs UTF-8 validation — non-UTF-8 values produce FromLuaConversionError before reaching handler code. Bypassing this would require accepting mlua::String + as_bytes() in every function, converting through OsStr::from_bytes(), and returning OsStr::as_bytes() back to Lua. This adds complexity across all path-accepting functions for a scenario (non-UTF-8 filenames) that is rare on modern systems.

References:

mlua String::to_str(): https://docs.rs/mlua/latest/mlua/struct.String.html
mlua string internals: https://deepwiki.com/mlua-rs/mlua/2.3.4-strings

§Quick start

use mlua::prelude::*;

let lua = Lua::new();
mlua_batteries::register_all(&lua, "std").unwrap();
// Lua: std.json.encode({a = 1})
// Lua: std.env.get("HOME")

§Custom configuration

// Requires the `sandbox` feature.
use mlua::prelude::*;
use mlua_batteries::config::Config;
use mlua_batteries::policy::Sandboxed;

let lua = Lua::new();
let config = Config::builder()
    .path_policy(Sandboxed::new(["/app/data"]).unwrap().read_only())
    .max_walk_depth(50)
    .build()
    .expect("invalid config");
mlua_batteries::register_all_with(&lua, "std", config).unwrap();

Modules§

config: Runtime configuration for mlua-batteries modules.
env: Environment variable module.
json: JSON encode/decode module.
path: Path manipulation module.
policy: Path access policy for sandboxing filesystem operations.
time: Time and measurement module.

Functions§

module_entries: Returns a list of (name, factory) pairs for all enabled modules.
register_all: Register all enabled modules with default configuration.
register_all_with: Register all enabled modules with custom configuration.

Type Aliases§

ModuleFactory: Module factory function type.