Support __todebugstring for pretty userdata debug output

Close #681

Author: khvzak

src/userdata.rs

@@ -123,6 +123,11 @@ pub enum MetaMethod {
     ///
     /// This is not an operator, but will be called by methods such as `tostring` and `print`.
     ToString,
+    /// The `__todebugstring` metamethod for debug purposes.
+    ///
+    /// This is an mlua-specific metamethod that can be used to provide debug representation for
+    /// userdata.
+    ToDebugString,
     /// The `__pairs` metamethod.
     ///
     /// This is not an operator, but it will be called by the built-in `pairs` function.
@@ -232,6 +237,7 @@ impl MetaMethod {
             MetaMethod::NewIndex => "__newindex",
             MetaMethod::Call => "__call",
             MetaMethod::ToString => "__tostring",
+            MetaMethod::ToDebugString => "__todebugstring",
 
             #[cfg(any(
                 feature = "lua55",

src/value.rs

@@ -151,7 +151,7 @@ impl Value {
     /// This might invoke the `__tostring` metamethod for non-primitive types (eg. tables,
     /// functions).
     pub fn to_string(&self) -> Result<String> {
-        unsafe fn invoke_to_string(vref: &ValueRef) -> Result<String> {
+        unsafe fn invoke_tostring(vref: &ValueRef) -> Result<String> {
             let lua = vref.lua.lock();
             let state = lua.state();
             let _guard = StackGuard::new(state);
@@ -178,9 +178,9 @@ impl Value {
             | Value::Function(Function(vref))
             | Value::Thread(Thread(vref, ..))
             | Value::UserData(AnyUserData(vref))
-            | Value::Other(vref) => unsafe { invoke_to_string(vref) },
+            | Value::Other(vref) => unsafe { invoke_tostring(vref) },
             #[cfg(feature = "luau")]
-            Value::Buffer(crate::Buffer(vref)) => unsafe { invoke_to_string(vref) },
+            Value::Buffer(crate::Buffer(vref)) => unsafe { invoke_tostring(vref) },
             Value::Error(err) => Ok(err.to_string()),
         }
     }
@@ -545,6 +545,24 @@ impl Value {
         ident: usize,
         visited: &mut HashSet<*const c_void>,
     ) -> fmt::Result {
+        unsafe fn invoke_tostring_dbg(vref: &ValueRef) -> Result<Option<String>> {
+            let lua = vref.lua.lock();
+            let state = lua.state();
+            let _guard = StackGuard::new(state);
+            check_stack(state, 3)?;
+
+            lua.push_ref(vref);
+            protect_lua!(state, 1, 1, fn(state) {
+                // Try `__todebugstring`  metamethod first, then `__tostring`
+                if ffi::luaL_callmeta(state, -1, cstr!("__todebugstring")) == 0 {
+                    if ffi::luaL_callmeta(state, -1, cstr!("__tostring")) == 0 {
+                        ffi::lua_pushnil(state);
+                    }
+                }
+            })?;
+            Ok(lua.pop_value().as_string().map(|s| s.to_string_lossy()))
+        }
+
         match self {
             Value::Nil => write!(fmt, "nil"),
             Value::Boolean(b) => write!(fmt, "{b}"),
@@ -561,15 +579,17 @@ impl Value {
             t @ Value::Table(_) => write!(fmt, "table: {:?}", t.to_pointer()),
             f @ Value::Function(_) => write!(fmt, "function: {:?}", f.to_pointer()),
             t @ Value::Thread(_) => write!(fmt, "thread: {:?}", t.to_pointer()),
-            u @ Value::UserData(ud) => {
-                // Try `__name/__type` first then `__tostring`
-                let name = ud.type_name().ok().flatten();
-                let s = name
-                    .map(|name| format!("{name}: {:?}", u.to_pointer()))
-                    .or_else(|| u.to_string().ok())
-                    .unwrap_or_else(|| format!("userdata: {:?}", u.to_pointer()));
-                write!(fmt, "{s}")
-            }
+            u @ Value::UserData(ud) => unsafe {
+                // Try converting to a (debug) string first, with fallback to `__name/__type`
+                match invoke_tostring_dbg(&ud.0) {
+                    Ok(Some(s)) => write!(fmt, "{s}"),
+                    _ => {
+                        let name = ud.type_name().ok().flatten();
+                        let name = name.as_deref().unwrap_or("userdata");
+                        write!(fmt, "{name}: {:?}", u.to_pointer())
+                    }
+                }
+            },
             #[cfg(feature = "luau")]
             buf @ Value::Buffer(_) => write!(fmt, "buffer: {:?}", buf.to_pointer()),
             Value::Error(e) if recursive => write!(fmt, "{e:?}"),

tests/value.rs

@@ -2,7 +2,9 @@ use std::collections::HashMap;
 use std::os::raw::c_void;
 use std::ptr;
 
-use mlua::{Error, LightUserData, Lua, MultiValue, Result, UserData, UserDataMethods, Value};
+use mlua::{
+    Error, LightUserData, Lua, MultiValue, Result, UserData, UserDataMethods, UserDataRegistry, Value,
+};
 
 #[test]
 fn test_value_eq() -> Result<()> {
@@ -218,6 +220,26 @@ fn test_debug_format() -> Result<()> {
         .map(Value::UserData)?;
     assert!(format!("{ud:#?}").starts_with("HashMap<i32, String>:"));
 
+    struct ToDebugUserData;
+    impl UserData for ToDebugUserData {
+        fn register(registry: &mut UserDataRegistry<Self>) {
+            registry.add_meta_method("__tostring", |_, _, ()| Ok("regular-string"));
+            registry.add_meta_method("__todebugstring", |_, _, ()| Ok("debug-string"));
+        }
+    }
+    let debug_ud = Value::UserData(lua.create_userdata(ToDebugUserData)?);
+    assert_eq!(debug_ud.to_string()?, "regular-string");
+    assert_eq!(format!("{debug_ud:#?}"), "debug-string");
+
+    struct ToStringUserData;
+    impl UserData for ToStringUserData {
+        fn register(registry: &mut UserDataRegistry<Self>) {
+            registry.add_meta_method("__tostring", |_, _, ()| Ok("to-string-only"));
+        }
+    }
+    let tostring_only_ud = Value::UserData(lua.create_userdata(ToStringUserData)?);
+    assert_eq!(format!("{tostring_only_ud:#?}"), "tostring-only");
+
     Ok(())
 }