Implement table to typed userdata conversion support

Author: Quahu

src/Laylua/Library/Marshaler/UserData/Attributes/Enums/LuaAllowedValueConversions.cs

@@ -85,12 +85,14 @@ public enum LuaAllowedValueConversions
     AllowOverflow = 1 << 9,
 
     /// <summary>
-    ///     The default policy: all conversions except <see cref="TableToObject"/>.
+    ///     The default policy: all conversions enabled.
     /// </summary>
-    Default = All & ~TableToObject,
+    Default = All,
 
     /// <summary>
     ///     All conversions enabled.
     /// </summary>
+#pragma warning disable CA1069
     All = StringToPrimitive | TableToObject | FunctionToCallableTarget | ObjectFallback | PrimitiveToString | StringToChar | StringToEnum | NumberToEnum | TruncateFraction | AllowOverflow,
+#pragma warning restore CA1069
 }

src/Laylua/Library/Marshaler/UserData/Attributes/Enums/LuaFromTableConversion.cs

@@ -0,0 +1,22 @@
+namespace Laylua.Marshaling;
+
+/// <summary>
+///     Controls whether source-generated typed userdata can be materialized from Lua tables.
+/// </summary>
+public enum LuaFromTableConversion
+{
+    /// <summary>
+    ///     Do not emit generated table-to-object conversion support for the type.
+    /// </summary>
+    Disabled = 1,
+
+    /// <summary>
+    ///     Emit generated table-to-object conversion support when the type has a supported parameterless-construction path.
+    /// </summary>
+    WhenTypeHasParameterlessConstructor = 2,
+
+    /// <summary>
+    ///     Require generated table-to-object conversion support and report an error when it cannot be emitted.
+    /// </summary>
+    Enabled = 3,
+}

src/Laylua/Library/Marshaler/UserData/Attributes/LuaTypeAttribute.cs

@@ -149,6 +149,17 @@ public sealed class LuaTypeAttribute : Attribute
     /// </remarks>
     public LuaAwaitableReturnHandling AwaitableReturnHandling { get; set; }
 
+    /// <summary>
+    ///     Gets or sets whether source-generated table-to-object conversion support is emitted for this type.
+    /// </summary>
+    /// <remarks>
+    ///     When not set, inherits from <see cref="LuaTypeDefaultsAttribute.FromTableConversion"/>
+    ///     (built-in default: <see cref="LuaFromTableConversion.WhenTypeHasParameterlessConstructor"/>).
+    ///     This controls whether the generated handler supports reading this type from a Lua table;
+    ///     <see cref="BindingConversions"/> still controls whether generated member binding is allowed to attempt table-to-object conversion.
+    /// </remarks>
+    public LuaFromTableConversion FromTableConversion { get; set; }
+
     /// <summary>
     ///     Gets or sets which value conversions are permitted during argument binding
     ///     and overload resolution for this type's generated callbacks.

src/Laylua/Library/Marshaler/UserData/Attributes/LuaTypeDefaultsAttribute.cs

@@ -152,6 +152,17 @@ public sealed class LuaTypeDefaultsAttribute : Attribute
     /// </remarks>
     public LuaAwaitableReturnHandling AwaitableReturnHandling { get; set; } = LuaAwaitableReturnHandling.ImplicitAwait;
 
+    /// <summary>
+    ///     Gets or sets the default source-generated table-to-object conversion support mode.
+    /// </summary>
+    /// <remarks>
+    ///     Defaults to <see cref="LuaFromTableConversion.WhenTypeHasParameterlessConstructor"/>.
+    ///     Applied when <see cref="LuaTypeAttribute.FromTableConversion"/> is not set.
+    ///     This controls whether generated handlers support reading their own type from a Lua table;
+    ///     <see cref="BindingConversions"/> still controls whether generated member binding is allowed to attempt table-to-object conversion.
+    /// </remarks>
+    public LuaFromTableConversion FromTableConversion { get; set; } = LuaFromTableConversion.WhenTypeHasParameterlessConstructor;
+
     /// <summary>
     ///     Gets or sets the default binding conversion policy for generated callbacks.
     /// </summary>

src/Laylua/Library/Marshaler/UserData/DynamicUserDataHandler.cs

@@ -1157,8 +1157,8 @@ public bool TryGetFromTable(lua_State* L, int stackIndex, out object? value)
             {
                 if (lua_type(L, -1) != LuaType.Nil)
                 {
-                    var propType = _writableProperties[luaName].PropertyType;
-                    if (!TryReadWithMarshaler(thread, -1, propType, out var fieldValue))
+                    var propertyType = _writableProperties[luaName].PropertyType;
+                    if (!TryReadWithMarshaler(thread, -1, propertyType, out var fieldValue))
                     {
                         value = default;
                         return false;

src/Laylua/Library/Marshaler/UserData/ILuaUserDataFromTable.cs

@@ -0,0 +1,19 @@
+using System.Diagnostics.CodeAnalysis;
+
+namespace Laylua.Marshaling;
+
+/// <summary>
+///     Defines a static conversion contract for reading a CLR value from a Lua table.
+/// </summary>
+/// <typeparam name="TUserData"> The CLR type being materialized. </typeparam>
+public interface ILuaUserDataFromTable<TUserData>
+{
+    /// <summary>
+    ///     Attempts to materialize a value from the specified Lua table.
+    /// </summary>
+    /// <param name="thread"> The owning Lua thread. </param>
+    /// <param name="table"> The source Lua table. </param>
+    /// <param name="value"> The materialized value when conversion succeeds. </param>
+    /// <returns> <see langword="true"/> when conversion succeeded; otherwise <see langword="false"/>. </returns>
+    static abstract bool TryGetFromTable(LuaThread thread, LuaTable table, [MaybeNullWhen(false)] out TUserData value);
+}

tests/Laylua.Tests/Tests/Analyzers/LuaTypeAnalyzerTests.cs

@@ -19,6 +19,7 @@ public sealed class LuaTypeAnalyzerTests
     private const string LuaTypeInvalidEnumConfigDiagnosticId = "LAYLUA107";
     private const string LuaTypeInvalidFlagsConfigDiagnosticId = "LAYLUA108";
     private const string LuaTypeNameCollisionDiagnosticId = "LAYLUA109";
+    private const string LuaTypeUnsupportedFromTableConversionDiagnosticId = "LAYLUA110";
 
 #if NET8_0
     private const string TargetFramework = "net8.0";
@@ -391,6 +392,128 @@ public static int create()
         Assert.That(result.Output, Does.Contain(LuaTypeNameCollisionDiagnosticId));
     }
 
+    [Test]
+    public void FromTableConversion_EnabledWithoutParameterlessConstructor_ReportsGeneratorError()
+    {
+        // Arrange
+        const string source = """
+                               using Laylua;
+                               using Laylua.Marshaling;
+
+                               [LuaType(FromTableConversion = LuaFromTableConversion.Enabled)]
+                               public partial class Sample
+                               {
+                                   public Sample(string value)
+                                   {
+                                   }
+                               }
+                               """;
+
+        // Act
+        var result = BuildSource(source);
+
+        // Assert
+        Assert.That(result.ExitCode, Is.Not.EqualTo(0));
+        Assert.That(result.Output, Does.Contain(LuaTypeUnsupportedFromTableConversionDiagnosticId));
+    }
+
+    [Test]
+    public void FromTableConversion_OptionalInitOnlyMember_ReportsGeneratorError()
+    {
+        // Arrange
+        const string source = """
+                               using Laylua.Marshaling;
+
+                               [LuaType]
+                               public partial class Sample
+                               {
+                                   public string Name { get; init; } = "";
+                               }
+                               """;
+
+        // Act
+        var result = BuildSource(source);
+
+        // Assert
+        Assert.That(result.ExitCode, Is.Not.EqualTo(0));
+        Assert.That(result.Output, Does.Contain(LuaTypeUnsupportedFromTableConversionDiagnosticId));
+    }
+
+    [Test]
+    public void FromTableConversion_IgnoredRequiredMember_ReportsGeneratorError()
+    {
+        // Arrange
+        const string source = """
+                               using Laylua.Marshaling;
+
+                               [LuaType]
+                               public partial class Sample
+                               {
+                                   [LuaIgnore]
+                                   public required string Hidden { get; init; }
+
+                                   public int Visible { get; set; }
+                               }
+                               """;
+
+        // Act
+        var result = BuildSource(source);
+
+        // Assert
+        Assert.That(result.ExitCode, Is.Not.EqualTo(0));
+        Assert.That(result.Output, Does.Contain(LuaTypeUnsupportedFromTableConversionDiagnosticId));
+    }
+
+    [Test]
+    public void TableConversionMethod_NonPublicCustomSignature_DoesNotReportGeneratorError()
+    {
+        // Arrange
+        const string source = """
+                               using Laylua;
+                               using Laylua.Marshaling;
+
+                               [LuaType]
+                               public partial class Sample
+                               {
+                                   private static bool TryGetFromTable(LuaThread thread, LuaTable table, out Sample value)
+                                   {
+                                       value = new Sample();
+                                       return true;
+                                   }
+                               }
+                               """;
+
+        // Act
+        var result = BuildSource(source);
+
+        // Assert
+        Assert.That(result.ExitCode, Is.EqualTo(0), result.Output);
+        Assert.That(result.Output, Does.Not.Contain(LuaTypeUnsupportedFromTableConversionDiagnosticId));
+    }
+
+    [Test]
+    public void TypeMember_NamedBindingConversions_DoesNotCollideWithGeneratedTableConversion()
+    {
+        // Arrange
+        const string source = """
+                               using Laylua.Marshaling;
+
+                               [LuaType]
+                               public partial class Sample
+                               {
+                                   private const int BindingConversions = 42;
+
+                                   public required string Name { get; init; }
+                               }
+                               """;
+
+        // Act
+        var result = BuildSource(source);
+
+        // Assert
+        Assert.That(result.ExitCode, Is.EqualTo(0), result.Output);
+    }
+
     private static BuildResult BuildSource(string source)
     {
         var tempPath = Path.Combine(Path.GetTempPath(), "LayluaAnalyzerTests", Guid.NewGuid().ToString("N"));

tests/Laylua.Tests/Tests/Marshaler/UserData/Dynamic/DynamicImplicitConversionTests.cs

@@ -74,6 +74,11 @@ public string AcceptsTarget(ImplicitConversionTarget target)
         return $"target:{target.Name}:{target.Value}";
     }
 
+    public string AcceptsConstructorTarget(DynamicTableConstructorTarget target)
+    {
+        return $"target:{target.Name}:{target.Health}:{target.ConstructorUsed}";
+    }
+
     public string NumericOrObject(double number)
     {
         return $"double:{number}";
@@ -96,7 +101,7 @@ public string LuaStringOnly(LuaString text)
 
     public string PointerOnly(IntPtr pointer)
     {
-        return $"ptr:0x{pointer.ToString("x")}";
+        return $"ptr:0x{pointer:x}";
     }
 
     public string CharOnly(char value)
@@ -135,13 +140,35 @@ public string StringOrEnum(ImplicitConversionStatus value)
     }
 }
 
-public class ImplicitConversionConstructable
+public class ImplicitConversionConstructable(ImplicitConversionTarget target)
+{
+    public string Summary { get; } = $"target:{target.Name}:{target.Value}";
+}
+
+public class DynamicTableRequiredInitTarget
+{
+    public required string Name { get; init; }
+
+    public int Health { get; set; }
+}
+
+public class DynamicTableConstructorTarget
 {
-    public string Summary { get; }
+    public string Name { get; }
+
+    public int Health { get; set; }
 
-    public ImplicitConversionConstructable(ImplicitConversionTarget target)
+    public bool ConstructorUsed { get; }
+
+    public DynamicTableConstructorTarget()
     {
-        Summary = $"target:{target.Name}:{target.Value}";
+        Name = "parameterless";
+    }
+
+    public DynamicTableConstructorTarget(string name)
+    {
+        Name = name;
+        ConstructorUsed = true;
     }
 }
 
@@ -154,18 +181,22 @@ public override void SetUp()
         LuaTypeRegistry.Unregister<ImplicitConversionTarget>();
         LuaTypeRegistry.Unregister<ImplicitConversionOverloaded>();
         LuaTypeRegistry.Unregister<ImplicitConversionConstructable>();
+        LuaTypeRegistry.Unregister<DynamicTableRequiredInitTarget>();
+        LuaTypeRegistry.Unregister<DynamicTableConstructorTarget>();
     }
 
     public override void TearDown()
     {
         LuaTypeRegistry.Unregister<ImplicitConversionTarget>();
         LuaTypeRegistry.Unregister<ImplicitConversionOverloaded>();
         LuaTypeRegistry.Unregister<ImplicitConversionConstructable>();
+        LuaTypeRegistry.Unregister<DynamicTableRequiredInitTarget>();
+        LuaTypeRegistry.Unregister<DynamicTableConstructorTarget>();
         base.TearDown();
     }
 
     [Test]
-    public void DefaultPolicy_Table_DoesNotBindToTypedUserDataParameter()
+    public void DefaultPolicy_Table_RemainsBehindObjectFallbackDuringOverloadResolution()
     {
         // Arrange
         LuaTypeRegistry.ConfigureDynamic<ImplicitConversionTarget>(static options =>
@@ -189,7 +220,7 @@ public void DefaultPolicy_Table_DoesNotBindToTypedUserDataParameter()
     }
 
     [Test]
-    public void DefaultPolicy_Table_DoesNotBindToTypedMethodParameter()
+    public void DefaultPolicy_Table_BindsToTypedMethodParameter()
     {
         // Arrange
         LuaTypeRegistry.ConfigureDynamic<ImplicitConversionTarget>(static options =>
@@ -205,8 +236,11 @@ public void DefaultPolicy_Table_DoesNotBindToTypedMethodParameter()
         var obj = new ImplicitConversionOverloaded();
         Lua["obj"] = obj;
 
-        // Act & Assert
-        Assert.Throws<LuaException>(() => Lua.Execute("obj:AcceptsTarget({Name = 'test'})"));
+        // Act
+        var result = Lua.Evaluate<string>("return obj:AcceptsTarget({Name = 'test'})");
+
+        // Assert
+        Assert.That(result, Is.EqualTo("target:test:0"));
     }
 
     [Test]
@@ -436,7 +470,7 @@ public void ObjectFallback_LowerPriority_ThanSpecificOverloads()
     }
 
     [Test]
-    public void DefaultPolicy_Table_DoesNotBindToTypedConstructorParameter()
+    public void DefaultPolicy_Table_BindsToTypedConstructorParameter()
     {
         // Arrange
         LuaTypeRegistry.ConfigureDynamic<ImplicitConversionTarget>(static options =>
@@ -452,8 +486,12 @@ public void DefaultPolicy_Table_DoesNotBindToTypedConstructorParameter()
 
         Lua["ImplicitConversionConstructable"] = typeof(ImplicitConversionConstructable);
 
-        // Act & Assert
-        Assert.Throws<LuaException>(() => Lua.Execute("return ImplicitConversionConstructable({Name = 'test', Value = 42})"));
+        // Act
+        var result = Lua.Evaluate<ImplicitConversionConstructable>("return ImplicitConversionConstructable({Name = 'test', Value = 42})");
+
+        // Assert
+        Assert.That(result, Is.Not.Null);
+        Assert.That(result!.Summary, Is.EqualTo("target:test:42"));
     }
 
     [Test]
@@ -597,7 +635,7 @@ public void LightUserData_DirectMatch_BindsPointerParameter()
 
         var obj = new ImplicitConversionOverloaded();
         Lua["obj"] = obj;
-        SetGlobalLightUserData("pointer", (IntPtr) 0x1234);
+        SetGlobalLightUserData("pointer", 0x1234);
 
         // Act
         var result = Lua.Evaluate<string>("return obj:PointerOnly(pointer)");