Add #[mlua::userdata] and #[mlua::userdata_impl] macros

Author: khvzak

Cargo.toml

@@ -42,7 +42,7 @@ async = ["dep:futures-util"]
 send = ["error-send"]
 error-send = []
 serde = ["dep:serde", "dep:erased-serde", "dep:serde-value", "bstr/serde"]
-macros = ["mlua_derive/macros"]
+macros = ["mlua_derive/macros", "dep:inventory"]
 anyhow = ["dep:anyhow", "error-send"]
 userdata-wrappers = ["parking_lot/send_guard"]
 
@@ -61,6 +61,7 @@ erased-serde = { version = "0.4", optional = true }
 serde-value = { version = "0.7", optional = true }
 parking_lot = { version = "0.12", features = ["arc_lock"] }
 anyhow = { version = "1.0", optional = true }
+inventory = { version = "0.3", optional = true }
 libc = "0.2"
 
 ffi = { package = "mlua-sys", version = "0.11.0-rc.1", path = "mlua-sys" }

examples/userdata.rs

@@ -1,45 +1,47 @@
-use mlua::{Lua, MetaMethod, Result, UserData, chunk};
+use mlua::{Lua, Result, chunk};
 
 #[derive(Default)]
+#[mlua::userdata]
 struct Rectangle {
     length: u32,
     width: u32,
 }
 
-impl UserData for Rectangle {
-    fn add_fields<F: mlua::UserDataFields<Self>>(fields: &mut F) {
-        fields.add_field_method_get("length", |_, this| Ok(this.length));
-        fields.add_field_method_set("length", |_, this, val| {
-            this.length = val;
-            Ok(())
-        });
-        fields.add_field_method_get("width", |_, this| Ok(this.width));
-        fields.add_field_method_set("width", |_, this, val| {
-            this.width = val;
-            Ok(())
-        });
+#[mlua::userdata_impl]
+impl Rectangle {
+    const NAME: &str = "Rectangle";
+
+    #[lua(infallible)]
+    fn new(length: u32, width: u32) -> Self {
+        Self { length, width }
+    }
+
+    #[lua(getter, name = "area", infallible)]
+    fn calculate_area(&self) -> u32 {
+        self.length * self.width
     }
 
-    fn add_methods<M: mlua::UserDataMethods<Self>>(methods: &mut M) {
-        methods.add_method("area", |_, this, ()| Ok(this.length * this.width));
-        methods.add_method("diagonal", |_, this, ()| {
-            Ok((this.length.pow(2) as f64 + this.width.pow(2) as f64).sqrt())
-        });
+    fn diagonal(&self) -> Result<f64> {
+        Ok((self.length.pow(2) as f64 + self.width.pow(2) as f64).sqrt())
+    }
 
-        // Constructor
-        methods.add_meta_function(MetaMethod::Call, |_, ()| Ok(Rectangle::default()));
+    // Constructor via `__call` metamethod
+    #[lua(meta, infallible)]
+    fn __call(length: u32, width: u32) -> Self {
+        Rectangle::new(length, width)
     }
 }
 
 fn main() -> Result<()> {
     let lua = Lua::new();
-    let rectangle = Rectangle::default();
+    lua.globals().set("Rectangle", lua.create_proxy::<Rectangle>()?)?;
     lua.load(chunk! {
-        local rect = $rectangle()
-        rect.width = 10
-        rect.length = 5
-        assert(rect:area() == 50)
-        assert(rect:diagonal() - 11.1803 < 0.0001)
+        local rect = Rectangle(10, 5)
+        rect.width = rect.width + 5
+        rect.length = rect.length + 5
+        assert(rect.NAME == "Rectangle")
+        assert(rect.area == 150)
+        assert(math.floor(rect:diagonal()) == 18)
     })
     .exec()
 }

mlua_derive/Cargo.toml

@@ -2,7 +2,7 @@
 name = "mlua_derive"
 version = "0.11.0"
 authors = ["Aleksandr Orlenko <zxteam@pm.me>"]
-edition = "2021"
+edition = "2024"
 description = "Procedural macros for the mlua crate."
 repository = "https://github.com/mlua-rs/mlua"
 keywords = ["lua", "mlua"]

mlua_derive/src/attr.rs

@@ -0,0 +1,87 @@
+use proc_macro2::Span;
+use syn::meta::ParseNestedMeta;
+use syn::{Ident, LitStr, Result};
+
+/// Parsed `#[lua(...)]` attribute.
+///
+/// Some flags are context-dependent:
+/// - Struct fields: `get`, `set`, `name`, `skip`
+/// - Impl methods: `getter`, `setter`, `static`, `meta`, `infallible`, `name`, `skip`
+#[derive(Default)]
+pub(crate) struct LuaAttr {
+    pub(crate) name: Option<String>,
+    pub(crate) infallible: bool,
+    pub(crate) skip: bool,
+
+    // Struct field context flags
+    pub(crate) get: bool,
+    pub(crate) set: bool,
+
+    // Impl method context flags
+    pub(crate) getter: bool,
+    pub(crate) setter: bool,
+    pub(crate) field: bool,
+    pub(crate) meta: bool,
+}
+
+impl LuaAttr {
+    pub(crate) fn parse_inner(&mut self, meta: ParseNestedMeta) -> Result<()> {
+        match &meta.path {
+            path if path.is_ident("skip") => {
+                if meta.value().is_ok() {
+                    return Err(meta.error("`skip` does not take a value"));
+                }
+                self.skip = true;
+            }
+            path if path.is_ident("infallible") => {
+                if meta.value().is_ok() {
+                    return Err(meta.error("`infallible` does not take a value"));
+                }
+                self.infallible = true;
+            }
+            path if path.is_ident("get") => self.get = true,
+            path if path.is_ident("set") => self.set = true,
+            path if path.is_ident("getter") => self.getter = true,
+            path if path.is_ident("setter") => self.setter = true,
+            path if path.is_ident("field") => self.field = true,
+            path if path.is_ident("meta") => self.meta = true,
+            path if path.is_ident("name") => {
+                let value = meta.value()?;
+                let lit: LitStr = value.parse()?;
+                self.name = Some(lit.value());
+            }
+            _ => {
+                return Err(meta.error(
+                    "unsupported lua attribute, expected: ".to_string()
+                        + "`skip`, `infallible`, `get`, `set`, `getter`, `setter`, `field`, `meta`, `name`",
+                ));
+            }
+        }
+        Ok(())
+    }
+
+    /// Returns the effective Lua name.
+    pub(crate) fn name(&self, ident: &Ident) -> String {
+        self.name.clone().unwrap_or_else(|| ident.to_string())
+    }
+
+    /// Returns the effective Lua metamethod name.
+    ///
+    /// If `name` is set via attribute, use it. Otherwise, if the function name
+    /// starts with `__`, use that. Returns an error if neither is available.
+    pub(crate) fn effective_meta_name(&self, fn_name: &Ident) -> Result<String> {
+        if let Some(ref name) = self.name {
+            return Ok(name.clone());
+        }
+        let fn_name = fn_name.to_string();
+        if fn_name.starts_with("__") {
+            return Ok(fn_name);
+        }
+        Err(syn::Error::new(
+            Span::call_site(),
+            format!(
+                "could not infer metamethod name from `{fn_name}`, either add `name = \"...\"` to `#[lua(meta, ...)]` or prefix the function with `__`"
+            ),
+        ))
+    }
+}

mlua_derive/src/from_lua.rs

@@ -1,6 +1,6 @@
 use proc_macro::TokenStream;
 use quote::quote;
-use syn::{parse_macro_input, DeriveInput};
+use syn::{DeriveInput, parse_macro_input};
 
 pub fn from_lua(input: TokenStream) -> TokenStream {
     let DeriveInput { ident, generics, .. } = parse_macro_input!(input as DeriveInput);

mlua_derive/src/lib.rs

@@ -2,14 +2,24 @@ use proc_macro::TokenStream;
 use proc_macro2::{Ident, Span};
 use quote::quote;
 use syn::meta::ParseNestedMeta;
-use syn::{parse_macro_input, ItemFn, LitStr, Result};
+use syn::{ItemFn, LitStr, Result, parse_macro_input};
 
 #[cfg(feature = "macros")]
 use {
-    crate::chunk::Chunk, proc_macro::TokenTree, proc_macro2::TokenStream as TokenStream2,
-    proc_macro_error2::proc_macro_error,
+    crate::chunk::Chunk, proc_macro::TokenTree, proc_macro_error2::proc_macro_error,
+    proc_macro2::TokenStream as TokenStream2,
 };
 
+#[cfg(feature = "macros")]
+macro_rules! try_compile {
+    ($expr:expr) => {
+        match $expr {
+            Ok(val) => val,
+            Err(err) => return err.to_compile_error().into(),
+        }
+    };
+}
+
 #[derive(Default)]
 struct ModuleAttributes {
     name: Option<Ident>,
@@ -151,9 +161,29 @@ pub fn from_lua(input: TokenStream) -> TokenStream {
     from_lua::from_lua(input)
 }
 
+/// Attribute macro for exposing a Rust type as a Lua userdata.
+#[cfg(feature = "macros")]
+#[proc_macro_attribute]
+pub fn userdata(attr: TokenStream, item: TokenStream) -> TokenStream {
+    userdata::userdata_type(attr, item)
+}
+
+/// Attribute macro for exposing impl block methods to Lua userdata.
+#[cfg(feature = "macros")]
+#[proc_macro_attribute]
+pub fn userdata_impl(attr: TokenStream, item: TokenStream) -> TokenStream {
+    userdata_impl::userdata_impl(attr, item)
+}
+
+#[cfg(feature = "macros")]
+mod attr;
 #[cfg(feature = "macros")]
 mod chunk;
 #[cfg(feature = "macros")]
 mod from_lua;
 #[cfg(feature = "macros")]
 mod token;
+#[cfg(feature = "macros")]
+mod userdata;
+#[cfg(feature = "macros")]
+mod userdata_impl;

mlua_derive/src/userdata.rs

@@ -0,0 +1,139 @@
+use proc_macro::TokenStream;
+use quote::{format_ident, quote};
+use syn::{Attribute, Data, DeriveInput, Error, Fields, FieldsNamed, Meta, parse_macro_input};
+
+use crate::attr::LuaAttr;
+
+/// Parse all `#[lua(...)]` attributes on a field, merging them into one `LuaAttr`.
+fn parse_field_lua_attr(attrs: &[Attribute]) -> syn::Result<LuaAttr> {
+    let mut lua_attr = LuaAttr::default();
+    for attr in attrs {
+        if attr.path().is_ident("lua")
+            && let Meta::List(_) = &attr.meta
+        {
+            attr.parse_nested_meta(|meta| lua_attr.parse_inner(meta))?;
+        }
+    }
+    Ok(lua_attr)
+}
+
+/// Strip `#[lua(...)]` attributes from a field, keeping all others.
+fn strip_lua_attrs(attrs: &[Attribute]) -> Vec<Attribute> {
+    (attrs.iter())
+        .filter(|attr| !attr.path().is_ident("lua"))
+        .cloned()
+        .collect()
+}
+
+pub fn userdata_type(attr: TokenStream, item: TokenStream) -> TokenStream {
+    if !attr.is_empty() {
+        return Error::new_spanned(
+            proc_macro2::TokenStream::from(attr),
+            "`#[userdata]` does not accept arguments",
+        )
+        .to_compile_error()
+        .into();
+    }
+
+    let mut input = parse_macro_input!(item as DeriveInput);
+    let type_name = &input.ident;
+
+    let mut named_fields: Option<&mut FieldsNamed> = match &mut input.data {
+        Data::Struct(data) => match &mut data.fields {
+            Fields::Named(fields) => Some(fields),
+            Fields::Unnamed(_) | Fields::Unit => None,
+        },
+        Data::Enum(_) => None,
+        Data::Union(_) => {
+            return Error::new_spanned(&input, "`#[userdata]` cannot be applied to unions")
+                .to_compile_error()
+                .into();
+        }
+    };
+
+    // Check for generic type parameters (not supported)
+    let has_type_params = input.generics.type_params().next().is_some();
+    if has_type_params {
+        return Error::new_spanned(
+            &input.generics,
+            "`#[userdata]` does not support generic type parameters. Wrap the generic type in a concrete newtype instead."
+        )
+        .to_compile_error()
+        .into();
+    }
+
+    let mut field_registrations = Vec::new();
+    if let Some(fields) = &mut named_fields {
+        for field in &fields.named {
+            let field_name = field.ident.as_ref().unwrap();
+
+            let lua_attr = try_compile!(parse_field_lua_attr(&field.attrs));
+            if lua_attr.skip {
+                continue;
+            }
+
+            let lua_name = lua_attr.name.unwrap_or_else(|| field_name.to_string());
+
+            // Assume get/set by default (unless explicitly specified)
+            let (has_get, has_set) = if lua_attr.get || lua_attr.set {
+                (lua_attr.get, lua_attr.set)
+            } else {
+                (true, true)
+            };
+
+            if has_get {
+                field_registrations.push(quote! {
+                    registry.add_field_method_get(#lua_name, |_lua, this| Ok(this.#field_name.clone()));
+                });
+            }
+            if has_set {
+                field_registrations.push(quote! {
+                    registry.add_field_method_set(#lua_name, |_lua, this, val| {
+                        this.#field_name = val;
+                        Ok(())
+                    });
+                });
+            }
+        }
+
+        // Strip mlua-specific attributes from fields before re-emitting
+        for field in &mut fields.named {
+            field.attrs = strip_lua_attrs(&field.attrs);
+        }
+    }
+
+    let registration_type_name = format_ident!("__MluaUserDataRegistration_{type_name}");
+    let register_fields_fn_name = format_ident!("__mlua_register_{type_name}_fields");
+
+    let output = quote! {
+        #input
+
+        #[doc(hidden)]
+        #[allow(non_camel_case_types)]
+        struct #registration_type_name {
+            register: fn(&mut ::mlua::userdata::UserDataRegistry<#type_name>),
+        }
+
+        ::mlua::__inventory::collect!(#registration_type_name);
+
+        #[allow(non_snake_case)]
+        fn #register_fields_fn_name(registry: &mut ::mlua::userdata::UserDataRegistry<#type_name>) {
+            use ::mlua::userdata::UserDataFields as _;
+            #(#field_registrations)*
+        }
+
+        ::mlua::__inventory::submit! {
+            #registration_type_name { register: #register_fields_fn_name }
+        }
+
+        impl ::mlua::userdata::UserData for #type_name {
+            fn register(registry: &mut ::mlua::userdata::UserDataRegistry<Self>) {
+                for item in ::mlua::__inventory::iter::<#registration_type_name> {
+                    (item.register)(registry);
+                }
+            }
+        }
+    };
+
+    output.into()
+}