Struct Lua 

pub struct Lua {
    raw: Rc<ReentrantMutex<RawLua>>,
    collect_garbage: bool,
}

Top level Lua struct which represents an instance of Lua VM.

Fields

raw: Rc<ReentrantMutex<RawLua>>

collect_garbage: bool

Implementations

impl Lua

pub fn new() -> Lua

Creates a new Lua state and loads the safe subset of the standard libraries.

Safety

The created Lua state will have some safety guarantees and will not allow to load unsafe standard libraries or C modules.

See StdLib documentation for a list of unsafe modules that cannot be loaded.

pub unsafe fn unsafe_new() -> Lua

Creates a new Lua state and loads all the standard libraries.

Safety

The created Lua state will not have safety guarantees and will allow to load C modules.

pub fn new_with(libs: StdLib, options: LuaOptions) -> Result<Lua, Error>

Creates a new Lua state and loads the specified safe subset of the standard libraries.

Use the StdLib flags to specify the libraries you want to load.

Safety

The created Lua state will have some safety guarantees and will not allow to load unsafe standard libraries or C modules.

See StdLib documentation for a list of unsafe modules that cannot be loaded.

pub unsafe fn unsafe_new_with(libs: StdLib, options: LuaOptions) -> Lua

Creates a new Lua state and loads the specified subset of the standard libraries.

Use the StdLib flags to specify the libraries you want to load.

Safety

The created Lua state will not have safety guarantees and allow to load C modules.

pub unsafe fn get_or_init_from_ptr<'a>(state: *mut lua_State) -> &'a Lua

Returns or constructs Lua instance from a raw state.

Once initialized, the returned Lua instance is cached in the registry and can be retrieved by calling this function again.

Safety

The Lua must outlive the chosen lifetime 'a.

pub unsafe fn exec_raw<R>( &self, args: impl IntoLuaMulti, f: impl FnOnce(*mut lua_State), ) -> Result<R, Error>

where R: FromLuaMulti,

Calls provided function passing a raw lua state.

The arguments will be pushed onto the stack before calling the function.

This method ensures that the Lua instance is locked while the function is called and restores Lua stack after the function returns.

Example

let lua = Lua::new();
let n: i32 = unsafe {
    let nums = (3, 4, 5);
    lua.exec_raw(nums, |state| {
        let n = ffi::lua_gettop(state);
        let mut sum = 0;
        for i in 1..=n {
            sum += ffi::lua_tointeger(state, i);
        }
        ffi::lua_pop(state, n);
        ffi::lua_pushinteger(state, sum);
    })
}?;
assert_eq!(n, 12);

pub fn load_std_libs(&self, libs: StdLib) -> Result<(), Error>

Loads the specified subset of the standard libraries into an existing Lua state.

Use the StdLib flags to specify the libraries you want to load.

pub fn register_module( &self, modname: &str, value: impl IntoLua, ) -> Result<(), Error>

Registers module into an existing Lua state using the specified value.

After registration, the given value will always be immediately returned when the given module is required.

pub fn preload_module(&self, modname: &str, func: Function) -> Result<(), Error>

Preloads module into an existing Lua state using the specified loader function.

When the module is required, the loader function will be called with module name as the first argument.

This is similar to setting the [package.preload[modname]] field.

[package.preload[modname]]: https://www.lua.org/manual/5.4/manual.html#pdf-package.preload

pub fn unload_module(&self, modname: &str) -> Result<(), Error>

Unloads module modname.

This method does not support unloading binary Lua modules since they are internally cached and can be unloaded only by closing Lua state.

This is similar to calling Lua::register_module with Nil value.

pub fn set_global_hook<F>( &self, triggers: HookTriggers, callback: F, ) -> Result<(), Error>

where F: Fn(&Lua, &Debug<'_>) -> Result<VmState, Error> + MaybeSend + 'static,

Sets or replaces a global hook function that will periodically be called as Lua code executes.

All new threads created (by mlua) after this call will use the global hook function.

For more information see Lua::set_hook.

pub fn set_hook<F>( &self, triggers: HookTriggers, callback: F, ) -> Result<(), Error>

where F: Fn(&Lua, &Debug<'_>) -> Result<VmState, Error> + MaybeSend + 'static,

Sets a hook function that will periodically be called as Lua code executes.

When exactly the hook function is called depends on the contents of the triggers parameter, see HookTriggers for more details.

The provided hook function can error, and this error will be propagated through the Lua code that was executing at the time the hook was triggered. This can be used to implement a limited form of execution limits by setting HookTriggers.every_nth_instruction and erroring once an instruction limit has been reached.

This method sets a hook function for the current thread of this Lua instance. If you want to set a hook function for another thread (coroutine), use Thread::set_hook instead.

Example

Shows each line number of code being executed by the Lua interpreter.

let lua = Lua::new();
lua.set_hook(HookTriggers::EVERY_LINE, |_lua, debug| {
    println!("line {:?}", debug.current_line());
    Ok(VmState::Continue)
});

lua.load(r#"
    local x = 2 + 3
    local y = x * 63
    local z = string.len(x..", "..y)
"#).exec()

pub fn remove_global_hook(&self)

Removes a global hook previously set by Lua::set_global_hook.

This function has no effect if a hook was not previously set.

pub fn remove_hook(&self)

Removes any hook from the current thread.

This function has no effect if a hook was not previously set.

pub fn inspect_stack<R>( &self, level: usize, f: impl FnOnce(&Debug<'_>) -> R, ) -> Option<R>

Gets information about the interpreter runtime stack at the given level.

This function calls callback f, passing the [Debug] structure that can be used to get information about the function executing at a given level. Level 0 is the current running function, whereas level n+1 is the function that has called level n (except for tail calls, which do not count in the stack).

pub fn traceback( &self, msg: Option<&str>, level: usize, ) -> Result<String, Error>

Creates a traceback of the call stack at the given level.

The msg parameter, if provided, is added at the beginning of the traceback. The level parameter works the same way as in Lua::inspect_stack.

pub fn used_memory(&self) -> usize

Returns the amount of memory (in bytes) currently used inside this Lua state.

pub fn set_memory_limit(&self, limit: usize) -> Result<usize, Error>

Sets a memory limit (in bytes) on this Lua state.

Once an allocation occurs that would pass this memory limit, a Error::MemoryError is generated instead. Returns previous limit (zero means no limit).

Does not work in module mode where Lua state is managed externally.

pub fn gc_stop(&self)

Stop the Lua GC from running

pub fn gc_restart(&self)

Restarts the Lua GC if it is not running

pub fn gc_collect(&self) -> Result<(), Error>

Perform a full garbage-collection cycle.

It may be necessary to call this function twice to collect all currently unreachable objects. Once to finish the current gc cycle, and once to start and finish the next cycle.

pub fn gc_step(&self) -> Result<bool, Error>

Steps the garbage collector one indivisible step.

Returns true if this has finished a collection cycle.

pub fn gc_step_kbytes(&self, kbytes: i32) -> Result<bool, Error>

Steps the garbage collector as though memory had been allocated.

if kbytes is 0, then this is the same as calling gc_step. Returns true if this step has finished a collection cycle.

pub fn gc_set_pause(&self, pause: i32) -> i32

Sets the pause value of the collector.

Returns the previous value of pause. More information can be found in the Lua documentation.

For Luau this parameter sets GC goal

pub fn gc_set_step_multiplier(&self, step_multiplier: i32) -> i32

Sets the step multiplier value of the collector.

Returns the previous value of the step multiplier. More information can be found in the Lua documentation.

pub fn gc_inc(&self, pause: i32, step_multiplier: i32, step_size: i32) -> GCMode

Changes the collector to incremental mode with the given parameters.

Returns the previous mode (always GCMode::Incremental in Lua < 5.4). More information can be found in the Lua documentation.

pub fn load<'a>(&self, chunk: impl AsChunk + 'a) -> Chunk<'a>

Returns Lua source code as a Chunk builder type.

In order to actually compile or run the resulting code, you must call Chunk::exec or similar on the returned builder. Code is not even parsed until one of these methods is called.

pub fn create_string(&self, s: impl AsRef<[u8]>) -> Result<String, Error>

Creates and returns an interned Lua string.

Lua strings can be arbitrary [u8] data including embedded nulls, so in addition to &str and &String, you can also pass plain &[u8] here.

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

Creates and returns a new empty table.

pub fn create_table_with_capacity( &self, narr: usize, nrec: usize, ) -> Result<Table, Error>

Creates and returns a new empty table, with the specified capacity.

• narr is a hint for how many elements the table will have as a sequence.
• nrec is a hint for how many other elements the table will have.

Lua may use these hints to preallocate memory for the new table.

pub fn create_table_from<K, V>( &self, iter: impl IntoIterator<Item = (K, V)>, ) -> Result<Table, Error>

where K: IntoLua, V: IntoLua,

Creates a table and fills it with values from an iterator.

pub fn create_sequence_from<T>( &self, iter: impl IntoIterator<Item = T>, ) -> Result<Table, Error>

where T: IntoLua,

Creates a table from an iterator of values, using 1.. as the keys.

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

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

Wraps a Rust function or closure, creating a callable Lua function handle to it.

The function’s return value is always a Result: If the function returns Err, the error is raised as a Lua error, which can be caught using (x)pcall or bubble up to the Rust code that invoked the Lua code. This allows using the ? operator to propagate errors through intermediate Lua code.

If the function returns Ok, the contained value will be converted to one or more Lua values. For details on Rust-to-Lua conversions, refer to the IntoLua and IntoLuaMulti traits.

Examples

Create a function which prints its argument:

let greet = lua.create_function(|_, name: String| {
    println!("Hello, {}!", name);
    Ok(())
});

Use tuples to accept multiple arguments:

let print_person = lua.create_function(|_, (name, age): (String, u8)| {
    println!("{} is {} years old!", name, age);
    Ok(())
});

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

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

Wraps a Rust mutable closure, creating a callable Lua function handle to it.

This is a version of Lua::create_function that accepts a FnMut argument.

pub unsafe fn create_c_function( &self, func: unsafe extern "C-unwind" fn(*mut lua_State) -> i32, ) -> Result<Function, Error>

Wraps a C function, creating a callable Lua function handle to it.

Safety

This function is unsafe because provides a way to execute unsafe C function.

pub fn create_thread(&self, func: Function) -> Result<Thread, Error>

Wraps a Lua function into a new thread (or coroutine).

Equivalent to coroutine.create.

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

where T: UserData + MaybeSend + 'static,

Creates a Lua userdata object from a custom userdata type.

All userdata instances of the same type T shares the same metatable.

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

where T: MaybeSend + 'static,

Creates a Lua userdata object from a custom Rust type.

You can register the type using Lua::register_userdata_type to add fields or methods before calling this method. Otherwise, the userdata object will have an empty metatable.

All userdata instances of the same type T shares the same metatable.

pub fn register_userdata_type<T>( &self, f: impl FnOnce(&mut UserDataRegistry<T>), ) -> Result<(), Error>

where T: 'static,

Registers a custom Rust type in Lua to use in userdata objects.

This methods provides a way to add fields or methods to userdata objects of a type T.

pub fn create_proxy<T>(&self) -> Result<AnyUserData, Error>

where T: UserData + 'static,

Create a Lua userdata “proxy” object from a custom userdata type.

Proxy object is an empty userdata object that has T metatable attached. The main purpose of this object is to provide access to static fields and functions without creating an instance of type T.

You can get or set uservalues on this object but you cannot borrow any Rust type.

Examples

struct MyUserData(i32);

impl UserData for MyUserData {
    fn add_fields<F: UserDataFields<Self>>(fields: &mut F) {
        fields.add_field_method_get("val", |_, this| Ok(this.0));
    }

    fn add_methods<M: UserDataMethods<Self>>(methods: &mut M) {
        methods.add_function("new", |_, value: i32| Ok(MyUserData(value)));
    }
}

lua.globals().set("MyUserData", lua.create_proxy::<MyUserData>()?)?;

lua.load("assert(MyUserData.new(321).val == 321)").exec()?;

pub fn type_metatable<T>(&self) -> Option<Table>

where T: LuaType,

Gets the metatable of a Lua built-in (primitive) type.

The metatable is shared by all values of the given type.

See Lua::set_type_metatable for examples.

pub fn set_type_metatable<T>(&self, metatable: Option<Table>)

where T: LuaType,

Sets the metatable for a Lua built-in (primitive) type.

The metatable will be shared by all values of the given type.

Examples

Change metatable for Lua boolean type:

let mt = lua.create_table()?;
mt.set("__tostring", lua.create_function(|_, b: bool| Ok(if b { "2" } else { "0" }))?)?;
lua.set_type_metatable::<bool>(Some(mt));
lua.load("assert(tostring(true) == '2')").exec()?;

pub fn globals(&self) -> Table

Returns a handle to the global environment.

pub fn set_globals(&self, globals: Table) -> Result<(), Error>

Sets the global environment.

This will replace the current global environment with the provided globals table.

For Lua 5.2+ the globals table is stored in the registry and shared between all threads. For Lua 5.1 and Luau the globals table is stored in each thread.

Please note that any existing Lua functions have cached global environment and will not see the changes made by this method. To update the environment for existing Lua functions, use Function::set_environment.

pub fn current_thread(&self) -> Thread

Returns a handle to the active Thread.

For calls to Lua this will be the main Lua thread, for parameters given to a callback, this will be whatever Lua thread called the callback.

pub fn scope<'env, R>( &self, f: impl for<'scope> FnOnce(&'scope Scope<'scope, 'env>) -> Result<R, Error>, ) -> Result<R, Error>

Calls the given function with a Scope parameter, giving the function the ability to create userdata and callbacks from Rust types that are !Send or non-'static.

The lifetime of any function or userdata created through Scope lasts only until the completion of this method call, on completion all such created values are automatically dropped and Lua references to them are invalidated. If a script accesses a value created through Scope outside of this method, a Lua error will result. Since we can ensure the lifetime of values created through Scope, and we know that Lua cannot be sent to another thread while Scope is live, it is safe to allow !Send data types and whose lifetimes only outlive the scope lifetime.

pub fn coerce_string(&self, v: Value) -> Result<Option<String>, Error>

Attempts to coerce a Lua value into a String in a manner consistent with Lua’s internal behavior.

To succeed, the value must be a string (in which case this is a no-op), an integer, or a number.

pub fn coerce_integer(&self, v: Value) -> Result<Option<i64>, Error>

Attempts to coerce a Lua value into an integer in a manner consistent with Lua’s internal behavior.

To succeed, the value must be an integer, a floating point number that has an exact representation as an integer, or a string that can be converted to an integer. Refer to the Lua manual for details.

pub fn coerce_number(&self, v: Value) -> Result<Option<f64>, Error>

Attempts to coerce a Lua value into a Number in a manner consistent with Lua’s internal behavior.

To succeed, the value must be a number or a string that can be converted to a number. Refer to the Lua manual for details.

pub fn pack(&self, t: impl IntoLua) -> Result<Value, Error>

Converts a value that implements IntoLua into a Value instance.

pub fn unpack<T>(&self, value: Value) -> Result<T, Error>

where T: FromLua,

Converts a Value instance into a value that implements FromLua.

pub fn convert<U>(&self, value: impl IntoLua) -> Result<U, Error>

where U: FromLua,

Converts a value that implements IntoLua into a FromLua variant.

pub fn pack_multi(&self, t: impl IntoLuaMulti) -> Result<MultiValue, Error>

Converts a value that implements IntoLuaMulti into a MultiValue instance.

pub fn unpack_multi<T>(&self, value: MultiValue) -> Result<T, Error>

where T: FromLuaMulti,

Converts a MultiValue instance into a value that implements FromLuaMulti.

pub fn set_named_registry_value( &self, key: &str, t: impl IntoLua, ) -> Result<(), Error>

Set a value in the Lua registry based on a string key.

This value will be available to Rust from all Lua instances which share the same main state.

pub fn named_registry_value<T>(&self, key: &str) -> Result<T, Error>

where T: FromLua,

Get a value from the Lua registry based on a string key.

Any Lua instance which shares the underlying main state may call this method to get a value previously set by Lua::set_named_registry_value.

pub fn unset_named_registry_value(&self, key: &str) -> Result<(), Error>

Removes a named value in the Lua registry.

Equivalent to calling Lua::set_named_registry_value with a value of Nil.

pub fn create_registry_value( &self, t: impl IntoLua, ) -> Result<RegistryKey, Error>

Place a value in the Lua registry with an auto-generated key.

This value will be available to Rust from all Lua instances which share the same main state.

Be warned, garbage collection of values held inside the registry is not automatic, see RegistryKey for more details. However, dropped RegistryKeys automatically reused to store new values.

pub fn registry_value<T>(&self, key: &RegistryKey) -> Result<T, Error>

where T: FromLua,

Get a value from the Lua registry by its RegistryKey

Any Lua instance which shares the underlying main state may call this method to get a value previously placed by Lua::create_registry_value.

pub fn remove_registry_value(&self, key: RegistryKey) -> Result<(), Error>

Removes a value from the Lua registry.

You may call this function to manually remove a value placed in the registry with Lua::create_registry_value. In addition to manual RegistryKey removal, you can also call Lua::expire_registry_values to automatically remove values from the registry whose RegistryKeys have been dropped.

pub fn replace_registry_value( &self, key: &mut RegistryKey, t: impl IntoLua, ) -> Result<(), Error>

Replaces a value in the Lua registry by its RegistryKey.

An identifier used in RegistryKey may possibly be changed to a new value.

See Lua::create_registry_value for more details.

pub fn owns_registry_value(&self, key: &RegistryKey) -> bool

Returns true if the given RegistryKey was created by a Lua which shares the underlying main state with this Lua instance.

Other than this, methods that accept a RegistryKey will return Error::MismatchedRegistryKey if passed a RegistryKey that was not created with a matching Lua state.

pub fn expire_registry_values(&self)

Remove any registry values whose RegistryKeys have all been dropped.

Unlike normal handle values, RegistryKeys do not automatically remove themselves on Drop, but you can call this method to remove any unreachable registry values not manually removed by Lua::remove_registry_value.

pub fn set_app_data<T>(&self, data: T) -> Option<T>

where T: MaybeSend + 'static,

Sets or replaces an application data object of type T.

Application data could be accessed at any time by using Lua::app_data_ref or Lua::app_data_mut methods where T is the data type.

Panics

Panics if the app data container is currently borrowed.

Examples

use mlua::{Lua, Result};

fn hello(lua: &Lua, _: ()) -> Result<()> {
    let mut s = lua.app_data_mut::<&str>().unwrap();
    assert_eq!(*s, "hello");
    *s = "world";
    Ok(())
}

fn main() -> Result<()> {
    let lua = Lua::new();
    lua.set_app_data("hello");
    lua.create_function(hello)?.call::<()>(())?;
    let s = lua.app_data_ref::<&str>().unwrap();
    assert_eq!(*s, "world");
    Ok(())
}

pub fn try_set_app_data<T>(&self, data: T) -> Result<Option<T>, T>

where T: MaybeSend + 'static,

Tries to set or replace an application data object of type T.

Returns:

• Ok(Some(old_data)) if the data object of type T was successfully replaced.
• Ok(None) if the data object of type T was successfully inserted.
• Err(data) if the data object of type T was not inserted because the container is currently borrowed.

See Lua::set_app_data for examples.

pub fn app_data_ref<T>(&self) -> Option<AppDataRef<'_, T>>

where T: 'static,

Gets a reference to an application data object stored by Lua::set_app_data of type T.

Panics

Panics if the data object of type T is currently mutably borrowed. Multiple immutable reads can be taken out at the same time.

pub fn try_app_data_ref<T>( &self, ) -> Result<Option<AppDataRef<'_, T>>, BorrowError>

where T: 'static,

Tries to get a reference to an application data object stored by Lua::set_app_data of type T.

pub fn app_data_mut<T>(&self) -> Option<AppDataRefMut<'_, T>>

where T: 'static,

Gets a mutable reference to an application data object stored by Lua::set_app_data of type T.

Panics

Panics if the data object of type T is currently borrowed.

pub fn try_app_data_mut<T>( &self, ) -> Result<Option<AppDataRefMut<'_, T>>, BorrowMutError>

where T: 'static,

Tries to get a mutable reference to an application data object stored by Lua::set_app_data of type T.

pub fn remove_app_data<T>(&self) -> Option<T>

where T: 'static,

Removes an application data of type T.

Panics

Panics if the app data container is currently borrowed.

pub fn weak(&self) -> WeakLua

Returns a weak reference to the Lua instance.

This is useful for creating a reference to the Lua instance that does not prevent it from being deallocated.

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<(), Error>

Formats the value using the given formatter.

impl Default for Lua

fn default() -> Lua

Returns the “default value” for a type.

impl Drop for Lua

fn drop(&mut self)

Executes the destructor for this type.