Struct hlua::LuaTable

pub struct LuaTable<L> { /* private fields */ }

Represents a table stored in the Lua context.

Just like you can read variables as integers and strings, you can also read Lua table by requesting a LuaTable object. Doing so will mutably borrow the object which you got the table from.

Example: reading a global variable

let mut lua = hlua::Lua::new();
lua.execute::<()>("a = {28, 92, 17};").unwrap();

let mut table: hlua::LuaTable<_> = lua.get("a").unwrap();
for (k, v) in table.iter::<i32, i32>().filter_map(|e| e) {
    println!("{} => {}", k, v);
}

Implementations

impl<'lua, L> LuaTable<L>

where L: AsMutLua<'lua>,

pub fn into_inner(self) -> L

Destroys the LuaTable and returns its inner Lua context. Useful when it takes Lua by value.

pub fn iter<K, V>(&mut self) -> LuaTableIterator<'_, L, K, V>

Iterates over the elements inside the table.

pub fn get<'a, R, I, E>(&'a mut self, index: I) -> Option<R>

where R: LuaRead<PushGuard<&'a mut LuaTable<L>>>, I: for<'b> PushOne<&'b mut &'a mut LuaTable<L>, Err = E>, E: Into<Void>,

Loads a value in the table given its index.

The index must implement the PushOne trait and the return type must implement the LuaRead trait. See the documentation at the crate root for more information.

Example: reading a table inside of a table.

let mut lua = hlua::Lua::new();
lua.execute::<()>("a = { 9, { 8, 7 }, 6 }").unwrap();

let mut table = lua.get::<hlua::LuaTable<_>, _>("a").unwrap();

assert_eq!(table.get::<i32, _, _>(1).unwrap(), 9);
assert_eq!(table.get::<i32, _, _>(3).unwrap(), 6);

{
    let mut subtable: hlua::LuaTable<_> = table.get(2).unwrap();
    assert_eq!(subtable.get::<i32, _, _>(1).unwrap(), 8);
    assert_eq!(subtable.get::<i32, _, _>(2).unwrap(), 7);
}

pub fn into_get<R, I, E>(self, index: I) -> Result<R, PushGuard<Self>>

where R: LuaRead<PushGuard<LuaTable<L>>>, I: for<'b> PushOne<&'b mut LuaTable<L>, Err = E>, E: Into<Void>,

Loads a value in the table, with the result capturing the table by value.

pub fn set<I, V, Ei, Ev>(&mut self, index: I, value: V)

where I: for<'r> PushOne<&'r mut LuaTable<L>, Err = Ei>, V: for<'r, 's> PushOne<&'r mut PushGuard<&'s mut LuaTable<L>>, Err = Ev>, Ei: Into<Void>, Ev: Into<Void>,

Inserts or modifies an elements of the table.

Contrary to checked_set, can only be called when writing the key and value cannot fail (which is the case for most types).

The index and the value must both implement the PushOne trait. See the documentation at the crate root for more information.

Examples found in repository

examples/sound-api.rs (line 13)

fn main() {
    let mut lua = hlua::Lua::new();
    lua.openlibs();

    // we create a fill an array named `Sound` which will be used as a class-like interface
    {
        let mut sound_namespace = lua.empty_array("Sound");

        // creating the `Sound.new` function
        sound_namespace.set("new", hlua::function0(|| Sound::new()));
    }

    lua.execute::<()>(r#"
        s = Sound.new();
        s:play();

        print("hello world from within lua!");
        print("is the sound playing:", s:is_playing());

        s:stop();
        print("is the sound playing:", s:is_playing());

    "#)
        .unwrap();
}

pub fn checked_set<I, V, Ke, Ve>( &mut self, index: I, value: V ) -> Result<(), CheckedSetError<Ke, Ve>>

where I: for<'r> PushOne<&'r mut LuaTable<L>, Err = Ke>, V: for<'r, 's> PushOne<&'r mut PushGuard<&'s mut LuaTable<L>>, Err = Ve>,

Inserts or modifies an elements of the table.

Returns an error if we failed to write the key and the value. This can only happen for a limited set of types. You are encouraged to use the set method if writing cannot fail.

pub fn empty_array<'s, I, E>( &'s mut self, index: I ) -> LuaTable<PushGuard<&'s mut LuaTable<L>>>

where I: for<'a> PushOne<&'a mut &'s mut LuaTable<L>, Err = E> + Clone, E: Into<Void>,

Inserts an empty array, then loads it.

pub fn get_or_create_metatable(self) -> LuaTable<PushGuard<L>>

Obtains or creates the metatable of the table.

A metatable is an additional table that can be attached to a table or a userdata. It can contain anything, but its most interesting usage are the following special methods:

• If non-nil, the __index entry of the metatable is used as a function whenever the user tries to read a non-existing entry in the table or userdata. Its signature is (object, index) -> value.
• If non-nil, the __newindex entry of the metatable is used as a function whenever the user tries to write a non-existing entry in the table or userdata. Its signature is (object, index, value).
• If non-nil, the __lt, __le and __eq entries correspond respectively to operators <, <= and ==. Their signature is (a, b) -> bool. Other operators are automatically derived from these three functions.
• If non-nil, the __add, __mul, __sub, __div, __unm, __pow and __concat entries correspond to operators +, *, -, /, - (unary), ^ and ... Their signature is (a, b) -> result.
• If non-nil, the __gc entry is called whenever the garbage collector is about to drop the object. Its signature is simply (obj). Remember that usercode is able to modify the metatable as well, so there is no strong guarantee that this is actually going to be called.

Interestingly enough, a metatable can also have a metatable. For example if you try to access a non-existing field in a table, Lua will look for the __index function in its metatable. If that function doesn’t exist, it will try to use the __index function of the metatable’s metatable in order to get the __index function of the metatable. This can go on infinitely.

Example

use hlua::Lua;
use hlua::LuaTable;
use hlua::AnyLuaValue;

let mut lua = Lua::new();
lua.execute::<()>("a = {}").unwrap();

{
    let mut table: LuaTable<_> = lua.get("a").unwrap();
    let mut metatable = table.get_or_create_metatable();
    metatable.set("__index", hlua::function2(|_: AnyLuaValue, var: String| -> AnyLuaValue {
        println!("The user tried to access non-existing index {:?}", var);
        AnyLuaValue::LuaNil
    }));
}

pub fn registry(lua: L) -> LuaTable<L>

Builds the LuaTable that yields access to the registry.

The registry is a special table available from anywhere and that is not directly accessible from Lua code. It can be used to store whatever you want to keep in memory.

Example

use hlua::Lua;
use hlua::LuaTable;

let mut lua = Lua::new();

let mut table = LuaTable::registry(&mut lua);
table.set(3, "hello");

Trait Implementations

impl<'lua, L> AsLua<'lua> for LuaTable<L>

where L: AsLua<'lua>,

fn as_lua(&self) -> LuaContext

impl<'lua, L> AsMutLua<'lua> for LuaTable<L>

where L: AsMutLua<'lua>,

fn as_mut_lua(&mut self) -> LuaContext

Returns the raw Lua context.

impl<L: Debug> Debug for LuaTable<L>

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

Formats the value using the given formatter.

impl<'lua, L> LuaRead<L> for LuaTable<L>

where L: AsMutLua<'lua>,

fn lua_read_at_position(lua: L, index: i32) -> Result<LuaTable<L>, L>

Reads the data from Lua at a given position.

fn lua_read(lua: L) -> Result<Self, L>

Reads the data from Lua.