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.

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.