Struct Lua 

pub struct Lua { /* private fields */ }

Primary owned embedding handle.

Lua is intentionally cheap to clone and single-threaded. State access is borrowed at the embedding boundary only; opcode dispatch still runs with direct &mut LuaState access. Captured Rust callbacks will need a call-path adapter that releases this boundary borrow before invoking user code.

Implementations

impl Lua

pub fn new() -> Self

Create a Lua runtime with parser and standard libraries installed.

Examples found in repository

examples/scope_world.rs (line 66)

fn main() -> Result<()> {
    let lua = Lua::new();
    let mut world = World::default();

    let count: i64 = lua.scope(|s| {
        let world_ud = s.create_userdata_ref_mut(&lua, &mut world)?;
        lua.globals().set("world", &world_ud)?;

        lua.load(
            r#"
            local a = world:spawn()
            local b = world:spawn()

            -- Direct mutation through a live sub-reference.
            local pa = world:position(a)
            pa.x, pa.y = 10, 20

            local pb = world:position(b)
            pb.x = pa.x + 5      -- reading pa here re-borrows; both are short-lived

            -- Stash one to prove it dies with the scope.
            escaped = world:position(a)

            return world:count()
        "#,
        )
        .eval()
    })?;

    println!("spawned {count} entities");
    // The mutations are visible to Rust after the scope returns.
    for (i, e) in world.entities.iter().enumerate() {
        println!("entity {i} = ({}, {})", e.x, e.y);
    }

    // The handle the script stashed on `escaped` is now invalid. Reading a
    // field raises a Lua error rather than touching the released `&mut World`.
    // We surface the message through Lua's own `pcall` + `tostring`, since the
    // error payload is a Lua value.
    let (ok, msg): (bool, String) = lua
        .load("local ok, e = pcall(function() return escaped.x end); return ok, tostring(e)")
        .eval()?;
    assert!(!ok, "stashed handle should be unusable after the scope");
    println!("post-scope use of a stashed handle -> {msg}");

    Ok(())
}

pub fn try_new() -> Result<Self>

Fallible variant of Lua::new.

pub fn with_hooks(hooks: HostHooks) -> Result<Self>

Create a Lua runtime with the supplied host capabilities.

pub fn load(&self, source: impl AsRef<[u8]>) -> Chunk

Load a Lua source chunk.

Examples found in repository

examples/scope_world.rs (lines 73-90)

fn main() -> Result<()> {
    let lua = Lua::new();
    let mut world = World::default();

    let count: i64 = lua.scope(|s| {
        let world_ud = s.create_userdata_ref_mut(&lua, &mut world)?;
        lua.globals().set("world", &world_ud)?;

        lua.load(
            r#"
            local a = world:spawn()
            local b = world:spawn()

            -- Direct mutation through a live sub-reference.
            local pa = world:position(a)
            pa.x, pa.y = 10, 20

            local pb = world:position(b)
            pb.x = pa.x + 5      -- reading pa here re-borrows; both are short-lived

            -- Stash one to prove it dies with the scope.
            escaped = world:position(a)

            return world:count()
        "#,
        )
        .eval()
    })?;

    println!("spawned {count} entities");
    // The mutations are visible to Rust after the scope returns.
    for (i, e) in world.entities.iter().enumerate() {
        println!("entity {i} = ({}, {})", e.x, e.y);
    }

    // The handle the script stashed on `escaped` is now invalid. Reading a
    // field raises a Lua error rather than touching the released `&mut World`.
    // We surface the message through Lua's own `pcall` + `tostring`, since the
    // error payload is a Lua value.
    let (ok, msg): (bool, String) = lua
        .load("local ok, e = pcall(function() return escaped.x end); return ok, tostring(e)")
        .eval()?;
    assert!(!ok, "stashed handle should be unusable after the scope");
    println!("post-scope use of a stashed handle -> {msg}");

    Ok(())
}

pub fn globals(&self) -> Table

Return the global environment table.

Examples found in repository

examples/scope_world.rs (line 71)

fn main() -> Result<()> {
    let lua = Lua::new();
    let mut world = World::default();

    let count: i64 = lua.scope(|s| {
        let world_ud = s.create_userdata_ref_mut(&lua, &mut world)?;
        lua.globals().set("world", &world_ud)?;

        lua.load(
            r#"
            local a = world:spawn()
            local b = world:spawn()

            -- Direct mutation through a live sub-reference.
            local pa = world:position(a)
            pa.x, pa.y = 10, 20

            local pb = world:position(b)
            pb.x = pa.x + 5      -- reading pa here re-borrows; both are short-lived

            -- Stash one to prove it dies with the scope.
            escaped = world:position(a)

            return world:count()
        "#,
        )
        .eval()
    })?;

    println!("spawned {count} entities");
    // The mutations are visible to Rust after the scope returns.
    for (i, e) in world.entities.iter().enumerate() {
        println!("entity {i} = ({}, {})", e.x, e.y);
    }

    // The handle the script stashed on `escaped` is now invalid. Reading a
    // field raises a Lua error rather than touching the released `&mut World`.
    // We surface the message through Lua's own `pcall` + `tostring`, since the
    // error payload is a Lua value.
    let (ok, msg): (bool, String) = lua
        .load("local ok, e = pcall(function() return escaped.x end); return ok, tostring(e)")
        .eval()?;
    assert!(!ok, "stashed handle should be unusable after the scope");
    println!("post-scope use of a stashed handle -> {msg}");

    Ok(())
}

pub fn create_table(&self) -> Result<Table>

Create a new empty table.

pub fn create_string(&self, bytes: impl AsRef<[u8]>) -> Result<LuaString>

Create a new Lua string from bytes.

pub fn create_function<A, R, F>(&self, func: F) -> Result<Function>

where A: FromLuaMulti + 'static, R: IntoLuaMulti + 'static, F: Fn(&Lua, A) -> Result<R> + 'static,

pub fn create_function_mut<A, R, F>(&self, func: F) -> Result<Function>

where A: FromLuaMulti + 'static, R: IntoLuaMulti + 'static, F: FnMut(&Lua, A) -> Result<R> + 'static,

pub fn create_userdata<T>(&self, data: T) -> Result<AnyUserData>

where T: UserData,

pub fn scope<F, R>(&self, f: F) -> Result<R>

where F: for<'scope> FnOnce(&Scope<'scope>) -> Result<R>,

Run f with a fresh Scope; any AnyUserData created via the scope is invalidated when f returns, so leaked references fail cleanly instead of using-after-the-borrow-ended.

use lua_rs_runtime::{Lua, UserData, UserDataMethods};

struct Counter { value: i64 }

impl UserData for Counter {
    fn add_methods<M: UserDataMethods<Self>>(methods: &mut M) {
        methods.add_method_mut("inc", |_lua, this, delta: i64| {
            this.value += delta;
            Ok(this.value)
        });
    }
}

let lua = Lua::new();
let mut counter = Counter { value: 0 };

lua.scope(|scope| {
    let ud = scope.create_userdata_ref_mut(&lua, &mut counter)?;
    lua.globals().set("c", &ud)?;
    lua.load("c:inc(5); c:inc(7)").exec()
}).unwrap();

assert_eq!(counter.value, 12);

// The script can stash the userdata on a global and try to use it
// later, but the call cleanly errors instead of touching the
// dropped `&mut counter`:
lua.scope(|scope| {
    let ud = scope.create_userdata_ref_mut(&lua, &mut counter)?;
    lua.globals().set("leaked", &ud)
}).unwrap();
assert!(lua.load("leaked:inc(1)").exec().is_err());

Examples found in repository

examples/scope_world.rs (lines 69-92)

fn main() -> Result<()> {
    let lua = Lua::new();
    let mut world = World::default();

    let count: i64 = lua.scope(|s| {
        let world_ud = s.create_userdata_ref_mut(&lua, &mut world)?;
        lua.globals().set("world", &world_ud)?;

        lua.load(
            r#"
            local a = world:spawn()
            local b = world:spawn()

            -- Direct mutation through a live sub-reference.
            local pa = world:position(a)
            pa.x, pa.y = 10, 20

            local pb = world:position(b)
            pb.x = pa.x + 5      -- reading pa here re-borrows; both are short-lived

            -- Stash one to prove it dies with the scope.
            escaped = world:position(a)

            return world:count()
        "#,
        )
        .eval()
    })?;

    println!("spawned {count} entities");
    // The mutations are visible to Rust after the scope returns.
    for (i, e) in world.entities.iter().enumerate() {
        println!("entity {i} = ({}, {})", e.x, e.y);
    }

    // The handle the script stashed on `escaped` is now invalid. Reading a
    // field raises a Lua error rather than touching the released `&mut World`.
    // We surface the message through Lua's own `pcall` + `tostring`, since the
    // error payload is a Lua value.
    let (ok, msg): (bool, String) = lua
        .load("local ok, e = pcall(function() return escaped.x end); return ok, tostring(e)")
        .eval()?;
    assert!(!ok, "stashed handle should be unusable after the scope");
    println!("post-scope use of a stashed handle -> {msg}");

    Ok(())
}

pub fn gc_collect(&self)

Run a full garbage-collection cycle.

impl Lua

pub fn sandboxed(config: SandboxConfig) -> Result<(Self, Sandbox)>

Create a Lua runtime with no host capabilities (no file, process, or dynamic-library hooks), the configured globals stripped, and an instruction/memory budget installed. Returns the runtime and a Sandbox handle for inspecting and resetting the budget.

pub fn install_sandbox(&self, config: SandboxConfig) -> Result<Sandbox>

Apply sandbox limits to this runtime: strip the configured globals and, if any runtime limit is set, install the runtime-wide budget. The budget lives in the shared GlobalState and is enforced natively in the VM on every thread, so code inside coroutines is metered too. Use this when you want to grant some host capabilities (build the Lua with selected HostHooks) but still bound execution.

Trait Implementations

impl Clone for Lua

fn clone(&self) -> Lua

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Lua

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.