Struct rlua::Context

pub struct Context<'lua> { /* private fields */ }

Implementations

impl<'lua> Context<'lua>

pub fn load<'a, S>(self, source: &'a S) -> Chunk<'lua, 'a> where
    S: ?Sized + AsRef<[u8]>, 

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<S>(self, s: &S) -> Result<String<'lua>> where
    S: ?Sized + AsRef<[u8]>, 

Create and return 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<'lua>>

Creates and returns a new table.

pub fn create_table_from<K, V, I>(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.

pub fn create_sequence_from<T, I>(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.

pub fn create_function<A, R, F>(self, func: F) -> Result<Function<'lua>> where
    A: FromLuaMulti<'lua>,
    R: ToLuaMulti<'lua>,
    F: 'static + Send + Fn(Context<'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 greet = lua_context.create_function(|_, name: String| {
    println!("Hello, {}!", name);
    Ok(())
});

Use tuples to accept multiple arguments:

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

pub fn create_function_mut<A, R, F>(self, func: F) -> Result<Function<'lua>> where
    A: FromLuaMulti<'lua>,
    R: ToLuaMulti<'lua>,
    F: 'static + Send + FnMut(Context<'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.

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

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

Equivalent to coroutine.create.

pub fn create_userdata<T>(self, data: T) -> Result<AnyUserData<'lua>> where
    T: 'static + Send + UserData, 

Create a Lua userdata object from a custom userdata type.

pub fn globals(self) -> Table<'lua>

Returns a handle to the global environment.

pub fn current_thread(self) -> Thread<'lua>

Returns a handle to the active Thread for this Context. For calls to Lua::context this will be the main Lua thread, for Context parameters given to a callback, this will be whatever Lua thread called the callback.

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

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 datatypes and whose lifetimes only outlive the scope lifetime.

Inside the scope callback, all handles created through Scope will share the same unique ’lua lifetime of the parent Context. This allows scoped and non-scoped values to be mixed in API calls, which is very useful (e.g. passing a scoped userdata to a non-scoped function). However, this also enables handles to scoped values to be trivially leaked from the given callback. This is not dangerous, though! After the callback returns, all scoped values are invalidated, which means that though references may exist, the Rust types backing them have dropped. Function types will error when called, and AnyUserData will be typeless. It would be impossible to prevent handles to scoped values from escaping anyway, since you would always be able to smuggle them through Lua state.

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

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<'lua>) -> Result<Option<Integer>>

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<'lua>) -> Result<Option<Number>>

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<T: ToLua<'lua>>(self, t: T) -> Result<Value<'lua>>

Converts a value that implements ToLua into a Value instance.

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

Converts a Value instance into a value that implements FromLua.

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

Converts a value that implements ToLuaMulti into a MultiValue instance.

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

Converts a MultiValue instance into a value that implements FromLuaMulti.

pub fn set_named_registry_value<S, T>(self, name: &S, t: T) -> Result<()> where
    S: ?Sized + AsRef<[u8]>,
    T: ToLua<'lua>, 

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.

pub fn named_registry_value<S, T>(self, name: &S) -> Result<T> where
    S: ?Sized + AsRef<[u8]>,
    T: FromLua<'lua>, 

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.

pub fn unset_named_registry_value<S: ?Sized + AsRef<[u8]>>(
    self,
    name: &S
) -> Result<()>

Removes a named value in the Lua registry.

Equivalent to calling set_named_registry_value with a value of Nil.

pub fn create_registry_value<T: ToLua<'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.

The returned RegistryKey is of 'static lifetime and is the main way in rlua of maintaining ownership of a Lua value outside of a Lua::context call.

Be warned, garbage collection of values held inside the registry is not automatic, see RegistryKey for more details.

pub fn registry_value<T: FromLua<'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.

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

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.

Trait Implementations

impl<'lua> Clone for Context<'lua>

fn clone(&self) -> Context<'lua>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<'lua> Debug for Context<'lua>

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

Formats the value using the given formatter.

impl<'lua> Copy for Context<'lua>