Trait UserDataTrait 

pub trait UserDataTrait: 'static {
    // Required methods
    fn type_name(&self) -> &'static str;
    fn as_any(&self) -> &dyn Any;
    fn as_any_mut(&mut self) -> &mut dyn Any;

    // Provided methods
    fn get_field(&self, _key: &str) -> Option<UdValue> { ... }
    fn set_field(
        &mut self,
        _key: &str,
        _value: UdValue,
    ) -> Option<Result<(), String>> { ... }
    fn lua_tostring(&self) -> Option<String> { ... }
    fn lua_eq(&self, _other: &dyn UserDataTrait) -> Option<bool> { ... }
    fn lua_lt(&self, _other: &dyn UserDataTrait) -> Option<bool> { ... }
    fn lua_le(&self, _other: &dyn UserDataTrait) -> Option<bool> { ... }
    fn lua_len(&self) -> Option<UdValue> { ... }
    fn lua_unm(&self) -> Option<UdValue> { ... }
    fn lua_add(&self, _other: &UdValue) -> Option<UdValue> { ... }
    fn lua_sub(&self, _other: &UdValue) -> Option<UdValue> { ... }
    fn lua_mul(&self, _other: &UdValue) -> Option<UdValue> { ... }
    fn lua_div(&self, _other: &UdValue) -> Option<UdValue> { ... }
    fn lua_mod(&self, _other: &UdValue) -> Option<UdValue> { ... }
    fn lua_concat(&self, _other: &UdValue) -> Option<UdValue> { ... }
    fn lua_gc(&mut self) { ... }
    fn lua_close(&mut self) { ... }
    fn field_names(&self) -> &'static [&'static str] { ... }
}

Describes how a userdata type can be accessed from Lua.

This trait provides rich, typed access to struct fields, methods, and standard operations. The #[derive(LuaUserData)] macro auto-implements this trait by exposing public fields. Methods are exposed via #[lua_methods] attribute macro on impl blocks, which generates static C wrapper functions returned from get_field as UdValue::Function(cfunction).

Dispatch priority (when Lua accesses obj.key):

1. get_field(key) — field or method access (fields return value, methods return CFunction)
2. Metatable __index — traditional Lua fallback

Example (manual implementation)

struct Point { x: f64, y: f64 }

impl UserDataTrait for Point {
    fn type_name(&self) -> &'static str { "Point" }

    fn get_field(&self, key: &str) -> Option<UdValue> {
        match key {
            "x" => Some(UdValue::Number(self.x)),
            "y" => Some(UdValue::Number(self.y)),
            _ => None,
        }
    }

    fn set_field(&mut self, key: &str, value: UdValue) -> Option<Result<(), String>> {
        match key {
            "x" => match value {
                UdValue::Number(n) => { self.x = n; Some(Ok(())) }
                _ => Some(Err("x must be a number".into()))
            }
            _ => None,
        }
    }

    fn as_any(&self) -> &dyn Any { self }
    fn as_any_mut(&mut self) -> &mut dyn Any { self }
}

Required Methods

fn type_name(&self) -> &'static str

Returns the type name displayed in error messages and type() calls. For derive macro: uses the struct name.

fn as_any(&self) -> &dyn Any

Downcast to &dyn Any for type-specific access.

fn as_any_mut(&mut self) -> &mut dyn Any

Downcast to &mut dyn Any for mutable type-specific access.

Provided Methods

fn get_field(&self, _key: &str) -> Option<UdValue>

Get a field value by name. Returns Some(value) if the field exists, None to fall through to metatable.

fn set_field( &mut self, _key: &str, _value: UdValue, ) -> Option<Result<(), String>>

Set a field value by name. Returns:

• Some(Ok(())) — field was set successfully
• Some(Err(msg)) — field exists but value is invalid (type mismatch, etc.)
• None — field not found, fall through to metatable __newindex

fn lua_tostring(&self) -> Option<String>

__tostring: String representation. Auto-generated when struct implements Display.

fn lua_eq(&self, _other: &dyn UserDataTrait) -> Option<bool>

__eq: Equality comparison. Auto-generated when struct implements PartialEq. other is guaranteed to be a &dyn UserDataTrait — downcast via as_any().

fn lua_lt(&self, _other: &dyn UserDataTrait) -> Option<bool>

__lt: Less-than comparison. Auto-generated when struct implements PartialOrd.

fn lua_le(&self, _other: &dyn UserDataTrait) -> Option<bool>

__le: Less-or-equal comparison. Auto-generated when struct implements PartialOrd.

fn lua_len(&self) -> Option<UdValue>

__len: Length operator (#obj). Auto-generated when struct has a .len() method.

fn lua_unm(&self) -> Option<UdValue>

__unm: Unary minus (-obj). Auto-generated when struct implements Neg.

fn lua_add(&self, _other: &UdValue) -> Option<UdValue>

__add: Addition (obj + other). Auto-generated when struct implements Add.

fn lua_sub(&self, _other: &UdValue) -> Option<UdValue>

__sub: Subtraction (obj - other). Auto-generated when struct implements Sub.

fn lua_mul(&self, _other: &UdValue) -> Option<UdValue>

__mul: Multiplication (obj * other). Auto-generated when struct implements Mul.

fn lua_div(&self, _other: &UdValue) -> Option<UdValue>

__div: Division (obj / other). Auto-generated when struct implements Div.

fn lua_mod(&self, _other: &UdValue) -> Option<UdValue>

__mod: Modulo (obj % other). Auto-generated when struct implements Rem.

fn lua_concat(&self, _other: &UdValue) -> Option<UdValue>

__concat: Concatenation (obj .. other).

fn lua_gc(&mut self)

__gc: Called when the userdata is garbage collected. Use this for cleanup (closing files, releasing resources, etc.).

fn lua_close(&mut self)

__close: Called when a to-be-closed variable goes out of scope.

fn field_names(&self) -> &'static [&'static str]

List available field names (for debugging, iteration, auto-completion).

Implementors

impl UserDataTrait for LuaFile