Module table 

Lua table handling.

Tables are Lua’s primary data structure, used for arrays, dictionaries, objects, modules, and more. This module provides types for creating and manipulating Lua tables from Rust.

Main Types

• Table - A handle to a Lua table.
• TablePairs - An iterator over key-value pairs in a table.
• TableSequence - An iterator over the array (sequence) portion of a table.

Basic Operations

Tables support key-value access similar to Rust’s HashMap:

let lua = Lua::new();
let table = lua.create_table()?;

// Set and get values
table.set("key", "value")?;
let value: String = table.get("key")?;
assert_eq!(value, "value");

// Keys and values can be any Lua-compatible type
table.set(1, "first")?;
table.set("nested", lua.create_table()?)?;

Array Operations

Tables can be used as arrays with 1-based indexing:

let lua = Lua::new();
let array = lua.create_table()?;

// Push values to the end (like Vec::push)
array.push("first")?;
array.push("second")?;
array.push("third")?;

// Pop from the end
let last: String = array.pop()?;
assert_eq!(last, "third");

// Get length
assert_eq!(array.raw_len(), 2);

Iteration

Iterate over all key-value pairs with Table::pairs:

let lua = Lua::new();
let table = lua.create_table()?;
table.set("a", 1)?;
table.set("b", 2)?;

for pair in table.pairs::<String, i32>() {
    let (key, value) = pair?;
    println!("{key} = {value}");
}

For array portions, use Table::sequence_values:

let lua = Lua::new();
let array = lua.create_sequence_from(["a", "b", "c"])?;

for value in array.sequence_values::<String>() {
    println!("{}", value?);
}

Raw vs Normal Access

Methods prefixed with raw_ (like Table::raw_get, Table::raw_set) bypass metamethods, directly accessing the table’s contents. Normal methods may trigger __index, __newindex, and other metamethods:

let lua = Lua::new();

// raw_set bypasses __newindex metamethod
let t = lua.create_table()?;
t.raw_set("key", "value")?;

// raw_get bypasses __index metamethod
let v: String = t.raw_get("key")?;

Metatables

Tables can have metatables that customize their behavior:

let lua = Lua::new();

let table = lua.create_table()?;
let metatable = lua.create_table()?;

// Set a default value via __index
metatable.set("__index", lua.create_function(|_, _: ()| Ok("default"))?)?;
table.set_metatable(Some(metatable))?;

// Accessing missing keys returns "default"
let value: String = table.get("missing")?;
assert_eq!(value, "default");

Global Table

The Lua global environment is itself a table, accessible via Lua::globals:

let lua = Lua::new();
let globals = lua.globals();

// Set a global variable
globals.set("my_var", 42)?;

// Now accessible from Lua code
let result: i32 = lua.load("my_var + 8").eval()?;
assert_eq!(result, 50);

Structs

Table

Handle to an internal Lua table.

TablePairs

An iterator over the pairs of a Lua table.

TableSequence

An iterator over the sequence part of a Lua table.