Struct rlua::Lua

pub struct Lua { /* fields omitted */ }

Top level Lua struct which holds the Lua state itself.

Methods

impl Lua

fn new() -> Lua

Creates a new Lua state and loads standard library without the debug library.

unsafe fn new_with_debug() -> Lua

Creates a new Lua state and loads the standard library including the debug library.

The debug library is very unsound, loading it and using it breaks all the guarantees of rlua.

fn load(&self, source: &str, name: Option<&str>) -> Result<Function>

Loads a chunk of Lua code and returns it as a function.

The source can be named by setting the name parameter. This is generally recommended as it results in better error traces.

Equivalent to Lua's load function.

fn exec<'lua, R: FromLuaMulti<'lua>>(
    &'lua self,
    source: &str,
    name: Option<&str>
) -> Result<R>

Execute a chunk of Lua code.

This is equivalent to simply loading the source with load and then calling the resulting function with no arguments.

Returns the values returned by the chunk.

fn eval<'lua, R: FromLuaMulti<'lua>>(
    &'lua self,
    source: &str,
    name: Option<&str>
) -> Result<R>

Evaluate the given expression or chunk inside this Lua state.

If source is an expression, returns the value it evaluates to. Otherwise, returns the values returned by the chunk (if any).

fn create_string(&self, s: &str) -> Result<String>

Pass a &str slice to Lua, creating and returning an interned Lua string.

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

Creates and returns a new table.

fn create_table_from<'lua, K, V, I>(&'lua self, cont: I) -> Result<Table<'lua>> where
    K: ToLua<'lua>,
    V: ToLua<'lua>,
    I: IntoIterator<Item = (K, V)>, 

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

fn create_sequence_from<'lua, T, I>(&'lua self, cont: I) -> Result<Table<'lua>> where
    T: ToLua<'lua>,
    I: IntoIterator<Item = T>, 

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

fn create_function<'lua, 'callback, A, R, F>(
    &'lua self,
    func: F
) -> Result<Function<'lua>> where
    A: FromLuaMulti<'callback>,
    R: ToLuaMulti<'callback>,
    F: 'static + Send + Fn(&'callback Lua, A) -> Result<R>, 

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 ToLua and ToLuaMulti traits.

Examples

Create a function which prints its argument:

let lua = Lua::new();

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

Use tuples to accept multiple arguments:

let lua = Lua::new();

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

fn create_function_mut<'lua, 'callback, A, R, F>(
    &'lua self,
    func: F
) -> Result<Function<'lua>> where
    A: FromLuaMulti<'callback>,
    R: ToLuaMulti<'callback>,
    F: 'static + Send + FnMut(&'callback Lua, A) -> Result<R>, 

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

This is a version of create_function that accepts a FnMut argument. Refer to create_function for more information about the implementation.

fn create_thread<'lua>(&'lua self, func: Function<'lua>) -> Result<Thread<'lua>>

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

Equivalent to coroutine.create.

fn create_userdata<T>(&self, data: T) -> Result<AnyUserData> where
    T: Send + UserData, 

Create a Lua userdata object from a custom userdata type.

fn globals(&self) -> Table

Returns a handle to the global environment.

fn scope<'scope, 'lua: 'scope, F, R>(&'lua self, f: F) -> R where
    F: FnOnce(&Scope<'scope>) -> R, 

Calls the given function with a Scope parameter, giving the function the ability to create userdata from rust types that are !Send, and rust callbacks that are !Send and not '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 datatypes and functions whose lifetimes only outlive the scope lifetime.

Handles that Lua::scope produces have a 'lua lifetime of the scope parameter, to prevent the handles from escaping the callback. However, this is not the only way for values to escape the callback, as they can be smuggled through Lua itself. This is safe to do, but not very useful, because after the scope is dropped, all references to scoped values, whether in Lua or in rust, are invalidated. Function types will error when called, and AnyUserData types will be typeless.

fn coerce_string<'lua>(&'lua self, v: Value<'lua>) -> Result<String<'lua>>

Coerces a Lua value to a string.

The value must be a string (in which case this is a no-op) or a number.

fn coerce_integer(&self, v: Value) -> Result<Integer>

Coerces a Lua value to an integer.

The value must be an integer, or a floating point number or a string that can be converted to an integer. Refer to the Lua manual for details.

fn coerce_number(&self, v: Value) -> Result<Number>

Coerce a Lua value to a number.

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

fn pack<'lua, T: ToLua<'lua>>(&'lua self, t: T) -> Result<Value<'lua>>

Converts a value that implements ToLua into a Value instance.

fn unpack<'lua, T: FromLua<'lua>>(&'lua self, value: Value<'lua>) -> Result<T>

Converts a Value instance into a value that implements FromLua.

fn pack_multi<'lua, T: ToLuaMulti<'lua>>(
    &'lua self,
    t: T
) -> Result<MultiValue<'lua>>

Converts a value that implements ToLuaMulti into a MultiValue instance.

fn unpack_multi<'lua, T: FromLuaMulti<'lua>>(
    &'lua self,
    value: MultiValue<'lua>
) -> Result<T>

Converts a MultiValue instance into a value that implements FromLuaMulti.

fn set_named_registry_value<'lua, T: ToLua<'lua>>(
    &'lua self,
    name: &str,
    t: T
) -> Result<()>

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

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

fn named_registry_value<'lua, T: FromLua<'lua>>(
    &'lua self,
    name: &str
) -> Result<T>

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

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

fn unset_named_registry_value<'lua>(&'lua self, name: &str) -> Result<()>

Removes a named value in the Lua registry.

Equivalent to calling set_named_registry_value with a value of Nil.

fn create_registry_value<'lua, T: ToLua<'lua>>(
    &'lua self,
    t: T
) -> Result<RegistryKey>

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.

fn registry_value<'lua, T: FromLua<'lua>>(
    &'lua self,
    key: &RegistryKey
) -> Result<T>

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 create_registry_value.

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

Removes a value from the Lua registry.

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

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.

fn expire_registry_values(&self)

Remove any registry values whose RegistryKeys have all been dropped.

Unlike normal handle values, RegistryKeys cannot automatically clean up their registry entries on Drop, but you can call this method to remove any unreachable registry values.

Trait Implementations

impl Send for Lua

impl Drop for Lua

fn drop(&mut self)

Executes the destructor for this type.