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")

§`require` instead of a global (Teal / htl)

register_all installs a global table, which is the convenient shape for plain Lua. A Teal project (htl lints global away) reaches the same modules through require: preload_all registers every enabled module in package.preload under <prefix>.<name>, plus the namespace itself under <prefix>, and touches no global. The declarations that let the Teal checker see them are in dts, written to a project’s types/ with the same prefix.

use mlua::prelude::*;

let lua = Lua::new();
mlua_batteries::preload_all(&lua, mlua_batteries::PRELOAD_PREFIX).unwrap();
// Lua / Teal: local json = require("mlua_batteries.json")
//             local std  = require("mlua_batteries")   -- every module in one table

§Async

The modules above are synchronous and need no runtime. Two opt-in pieces are async, and both want a tokio current-thread runtime driving a LocalSet:

task — structured concurrency primitives (std.task.*).
async_overrides — replaces the blocking entries of an already-registered namespace (std.time.sleep, std.proc.pipeline, std.http.*, std.fs.*) with async ones, so they no longer park the VM thread. Same Lua-side API; opt in by calling it after register_all.

§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§

argparse: Command-line argument parsing from a spec table — std.argparse.
config: Runtime configuration for mlua-batteries modules.
dts: Teal declarations (.d.tl) for the Lua modules, shipped with the crate.
env: Environment variable module.
json: JSON encode/decode module.
path: Path manipulation module.
policy: Path access policy for sandboxing filesystem operations.
pretty: Deterministic value dump for debugging, snapshots and test output.
string: Extended string operations (Unicode-aware).
time: Time and measurement module.
validate: Table validation module.

Constants§

PRELOAD_PREFIX: The require prefix this crate’s shipped Teal declarations are named under (require("mlua_batteries.json")), and the one to pass preload_all unless the host composes its own namespace.

Functions§

module_entries: Returns a list of (name, factory) pairs for all enabled modules.
preload_all: Register every enabled module in package.preload with default configuration.
preload_all_with: Register every enabled module in package.preload with custom configuration.
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.