feat: FluentResult (#13)

* fix(Readme): typo

* fix(Readme): typos in code example

* feat(FluentReturn): add FluentReturnAttribute

* feat(FluentReturn): bookkeep return type and respectReturnType values

* refactor(InnerBodyCreation): rename classes

* refactor(InnerBodyGeneration): rename methods

* refactor(InnerBodyGeneration): rename method

* test: add FluentReturnSingleStepClass

* feat(TestDataProvider): add filter method for running a single test

* feat(Generics): make FluentReturnSingleStepClass test work

* refactor(BuilderStepMethod): add CreateMethod and CreateInterfaceMethod methods

* fix(InnerBodyForMethodGenerator): use parameter returnType

* test: FluentReturnSingleStepPrivateMethodsClass

* feat(FluentReturn): adjust BuildReflectionCodeWithRefAndOutParameters method

* test: FluentReturn method with ref parameter

* fix(InnerBodyForMethodGenerator): suppress nullability for methods that return a result

* test: FluentReturnMultiStepClass and FluentReturnMultiStepPrivateMethodsClass

* feat(CodeGenerationTests): write generated code only if it changed

* fix(FluentReturnMultiStepClass): remove unused using

* test: CanExecuteFluentReturnSingleStepPrivateMethodsClass and CanExecuteFluentReturnMultiStepPrivateMethodsClass

* feat: detect conflicting control attributes FluentBreak and FluentReturn

* docs(Readme): fix typo

* test: ContinueWithOfOverloadedMethodClass

* feat(Storybook): add FluentReturn example

* docs(Readme): add FluentReturn description and example

* chore: increase nuget versions to 1.3.0

* chore(Nuget): add readme

Author: m31coding

README.md

@@ -25,7 +25,7 @@ PM> Install-Package M31.FluentApi
 A package reference will be added to your `csproj` file. Moreover, since this library provides code via source code generation, consumers of your project don't need the reference to `M31.FluentApi`. Therefore, it is recommended to use the `PrivateAssets` metadata tag:
 
 ```xml
-<PackageReference Include="M31.FluentApi" Version="1.2.0" PrivateAssets="all"/>
+<PackageReference Include="M31.FluentApi" Version="1.3.0" PrivateAssets="all"/>
 ```
 
 If you would like to examine the generated code, you may emit it by adding the following lines to your `csproj` file:
@@ -103,7 +103,7 @@ The attributes `FluentPredicate` and `FluentCollection` can be used instead of a
 
 The `FluentMethod` attribute is used for custom builder method implementations.
 
-The control attribute `FluentContinueWith` indicates a jump to the specified builder step, and `FluentBreak` stops the builder.
+The control attribute `FluentContinueWith` indicates a jump to the specified builder step, and `FluentBreak` stops the builder. `FluentReturn` allows returning arbitrary types and values within the generated API.
 
 
 ### FluentApi
@@ -310,6 +310,24 @@ private void WhoseAddressIsUnknown()
 ...WhoseAddressIsUnknown();
 ```
 
+### FluentReturn
+
+Allows the builder to respect the return value of the decorated method, enabling the return of arbitrary types and values within the generated API. If a void method is decorated with this attribute, the builder method will also return void.
+                
+```cs
+[FluentMethod(1)]
+[FluentReturn]
+public string ToJson()
+{
+    return JsonSerializer.Serialize(this);
+}
+```
+
+```cs
+string serialized = ...ToJson();
+```
+
+
 ### Forks
 
 To create forks specify builder methods at the same builder step. The resulting API offers all specified methods at this step but only one can be called:
@@ -319,11 +337,11 @@ To create forks specify builder methods at the same builder step. The resulting
 public int Age { get; private set; }
 
 [FluentMethod(1)]
-private void BornOn(DateOnldateOfBirth)
+private void BornOn(DateOnly dateOfBirth)
 {
-    DateOnly today = DateOnlFromDateTime(DateTime.Today);
-    int age = today.Year dateOfBirth.Year;
-    if (dateOfBirth > today.AddYea(-age)) age--;
+    DateOnly today = DateOnly.FromDateTime(DateTime.Today);
+    int age = today.Year - dateOfBirth.Year;
+    if (dateOfBirth > today.AddYears(-age)) age--;
     Age = age;
 }
 ```

src/M31.FluentApi.Generator/CodeGeneration/CodeBoardActors/BuilderStepsGeneration/BuilderStepMethod.cs

@@ -14,8 +14,22 @@ protected BuilderStepMethod(BuilderMethod builderMethod)
 
     internal abstract Method BuildMethodCode(BuilderAndTargetInfo info);
 
-    protected MethodSignature CreateMethodSignature(string returnType, params string[] modifiers)
+    protected Method CreateMethod(string defaultReturnType, params string[] modifiers)
     {
+        MethodSignature methodSignature = CreateMethodSignature(defaultReturnType, modifiers);
+        return new Method(methodSignature);
+    }
+
+    protected Method CreateInterfaceMethod(string interfaceName, string defaultReturnType, params string[] modifiers)
+    {
+        MethodSignature methodSignature = CreateMethodSignature(defaultReturnType, modifiers);
+        return new InterfaceMethod(methodSignature, interfaceName);
+    }
+
+    private MethodSignature CreateMethodSignature(string defaultReturnType, params string[] modifiers)
+    {
+        string returnType = ReturnTypeToRespect ?? defaultReturnType;
+
         MethodSignature signature = MethodSignature.Create(returnType, MethodName, false);
         signature.AddModifiers(modifiers);
 
@@ -39,10 +53,18 @@ protected MethodSignature CreateMethodSignature(string returnType, params string
 
     protected void CreateBody(Method method, string instancePrefix)
     {
-        List<string> bodyCode = BuildBodyCode(instancePrefix);
+        List<string> bodyCode = BuildBodyCode(instancePrefix, ReturnTypeToRespect);
         foreach (string bodyLine in bodyCode)
         {
             method.AppendBodyLine(bodyLine);
         }
     }
+
+    protected void CreateReturnStatement(Method method, string defaultReturnStatement)
+    {
+        if (ReturnTypeToRespect == null)
+        {
+            method.AppendBodyLine(defaultReturnStatement);
+        }
+    }
 }

src/M31.FluentApi.Generator/CodeGeneration/CodeBoardActors/BuilderStepsGeneration/FirstStepBuilderMethod.cs

@@ -18,8 +18,7 @@ internal FirstStepBuilderMethod(BuilderMethod builderMethod, string returnType)
     internal override Method BuildMethodCode(BuilderAndTargetInfo info)
     {
         // public static IBornOn WithName(string name)
-        MethodSignature methodSignature = CreateMethodSignature(ReturnType, "public", "static");
-        Method method = new Method(methodSignature);
+        Method method = CreateMethod(ReturnType, "public", "static");
 
         // CreateStudent<T1, T2> createStudent = new CreateStudent<T1, T2>();
         method.AppendBodyLine(
@@ -30,7 +29,7 @@ internal override Method BuildMethodCode(BuilderAndTargetInfo info)
         CreateBody(method, $"{info.BuilderInstanceName}.");
 
         // return createStudent;
-        method.AppendBodyLine($"return {info.BuilderInstanceName};");
+        CreateReturnStatement(method, $"return {info.BuilderInstanceName};");
 
         return method;
     }

src/M31.FluentApi.Generator/CodeGeneration/CodeBoardActors/BuilderStepsGeneration/InterjacentBuilderMethod.cs

@@ -20,14 +20,13 @@ internal InterjacentBuilderMethod(BuilderMethod builderMethod, string returnType
     internal override Method BuildMethodCode(BuilderAndTargetInfo info)
     {
         // public IInSemester BornOn(System.DateOnly dateOfBirth)
-        MethodSignature methodSignature = CreateMethodSignature(ReturnType, "public");
-        Method method = new InterfaceMethod(methodSignature, InterfaceName);
+        Method method = CreateInterfaceMethod(InterfaceName, ReturnType, "public");
 
         // student.DateOfBirth = dateOfBirth;
         CreateBody(method, string.Empty);
 
         // return this;
-        method.AppendBodyLine($"return this;");
+        CreateReturnStatement(method, "return this;");
 
         return method;
     }

src/M31.FluentApi.Generator/CodeGeneration/CodeBoardActors/BuilderStepsGeneration/LastStepBuilderMethod.cs

@@ -18,14 +18,13 @@ internal LastStepBuilderMethod(BuilderMethod builderMethod, string interfaceName
     internal override Method BuildMethodCode(BuilderAndTargetInfo info)
     {
         // public Student<T1, T2> InSemester(int semester)
-        MethodSignature methodSignature = CreateMethodSignature(info.FluentApiClassNameWithTypeParameters, "public");
-        Method method = new InterfaceMethod(methodSignature, InterfaceName);
+        Method method = CreateInterfaceMethod(InterfaceName, info.FluentApiClassNameWithTypeParameters, "public");
 
         // student.Semester = semester;
         CreateBody(method, string.Empty);
 
         // return student;
-        method.AppendBodyLine($"return {info.ClassInstanceName};");
+        CreateReturnStatement(method, $"return {info.ClassInstanceName};");
 
         return method;
     }

src/M31.FluentApi.Generator/CodeGeneration/CodeBoardActors/BuilderStepsGeneration/SingleStepBuilderMethod.cs

@@ -15,9 +15,7 @@ internal SingleStepBuilderMethod(BuilderMethod builderMethod)
     internal override Method BuildMethodCode(BuilderAndTargetInfo info)
     {
         // public static Student<T1, T2> InSemester(int semester)
-        MethodSignature methodSignature =
-            CreateMethodSignature(info.FluentApiClassNameWithTypeParameters, "public", "static");
-        Method method = new Method(methodSignature);
+        Method method = CreateMethod(info.FluentApiClassNameWithTypeParameters, "public", "static");
 
         // CreateStudent<T1, T2> createStudent = new CreateStudent<T1, T2>();
         method.AppendBodyLine(
@@ -28,7 +26,7 @@ internal override Method BuildMethodCode(BuilderAndTargetInfo info)
         CreateBody(method, $"{info.BuilderInstanceName}.");
 
         // return createStudent.student;
-        method.AppendBodyLine($"return {info.BuilderInstanceName}.{info.ClassInstanceName};");
+        CreateReturnStatement(method, $"return {info.BuilderInstanceName}.{info.ClassInstanceName};");
 
         return method;
     }

src/M31.FluentApi.Generator/CodeGeneration/CodeBoardActors/Commons/BuildBodyCode.cs

@@ -1,3 +1,3 @@
 namespace M31.FluentApi.Generator.CodeGeneration.CodeBoardActors.Commons;
 
-internal delegate List<string> BuildBodyCode(string instancePrefix);
+internal delegate List<string> BuildBodyCode(string instancePrefix, string? returnType);

src/M31.FluentApi.Generator/CodeGeneration/CodeBoardActors/Commons/BuilderMethod.cs

@@ -8,17 +8,20 @@ internal class BuilderMethod
     internal string MethodName { get; }
     internal GenericInfo? GenericInfo { get; }
     internal IReadOnlyCollection<Parameter> Parameters { get; }
+    internal string? ReturnTypeToRespect { get; }
     internal BuildBodyCode BuildBodyCode { get; }
 
     internal BuilderMethod(
         string methodName,
         GenericInfo? genericInfo,
         IReadOnlyCollection<Parameter> parameters,
+        string? returnTypeToRespect,
         BuildBodyCode buildBodyCode)
     {
         MethodName = methodName;
         GenericInfo = genericInfo;
         Parameters = parameters;
+        ReturnTypeToRespect = returnTypeToRespect;
         BuildBodyCode = buildBodyCode;
     }
 
@@ -27,6 +30,7 @@ internal BuilderMethod(BuilderMethod builderMethod)
         MethodName = builderMethod.MethodName;
         GenericInfo = builderMethod.GenericInfo;
         Parameters = builderMethod.Parameters;
+        ReturnTypeToRespect = builderMethod.ReturnTypeToRespect;
         BuildBodyCode = builderMethod.BuildBodyCode;
     }
 }

src/M31.FluentApi.Generator/CodeGeneration/CodeBoardActors/Commons/BuilderMethodFactory.cs

@@ -14,7 +14,7 @@ internal BuilderMethodFactory(InnerBodyCreationDelegates innerBodyCreationDelega
 
     internal BuilderMethod CreateBuilderMethod(string methodName)
     {
-        return new BuilderMethod(methodName, null, new List<Parameter>(), _ => new List<string>());
+        return new BuilderMethod(methodName, null, new List<Parameter>(), null, (_, _) => new List<string>());
     }
 
     internal BuilderMethod CreateBuilderMethod(string methodName, ComputeValueCode computeValue)
@@ -23,7 +23,7 @@ internal BuilderMethod CreateBuilderMethod(string methodName, ComputeValueCode c
             ? new List<Parameter>() { computeValue.Parameter }
             : new List<Parameter>();
 
-        List<string> BuildBodyCode(string instancePrefix)
+        List<string> BuildBodyCode(string instancePrefix, string? returnType)
         {
             return new List<string>()
             {
@@ -32,25 +32,28 @@ List<string> BuildBodyCode(string instancePrefix)
             };
         }
 
-        return new BuilderMethod(methodName, null, parameters, BuildBodyCode);
+        return new BuilderMethod(methodName, null, parameters, null, BuildBodyCode);
     }
 
     internal BuilderMethod CreateBuilderMethod(string methodName, List<ComputeValueCode> computeValues)
     {
         List<Parameter> parameters = computeValues.Select(v => v.Parameter).OfType<Parameter>().ToList();
 
-        List<string> BuildBodyCode(string instancePrefix)
+        List<string> BuildBodyCode(string instancePrefix, string? returnType)
         {
             return computeValues
                 .Select(v =>
                     innerBodyCreationDelegates.GetSetMemberCode(v.TargetMember).BuildCode(instancePrefix, v.Code))
                 .ToList();
         }
 
-        return new BuilderMethod(methodName, null, parameters, BuildBodyCode);
+        return new BuilderMethod(methodName, null, parameters, null, BuildBodyCode);
     }
 
-    internal BuilderMethod CreateBuilderMethod(MethodSymbolInfo methodSymbolInfo, string methodName)
+    internal BuilderMethod CreateBuilderMethod(
+        MethodSymbolInfo methodSymbolInfo,
+        string methodName,
+        bool respectReturnType)
     {
         List<Parameter> parameters = methodSymbolInfo.ParameterInfos
             .Select(i => new Parameter(
@@ -61,11 +64,19 @@ internal BuilderMethod CreateBuilderMethod(MethodSymbolInfo methodSymbolInfo, st
                 new ParameterAnnotations(i.ParameterKinds)))
             .ToList();
 
-        List<string> BuildBodyCode(string instancePrefix)
+        string? returnTypeToRespect = respectReturnType ? methodSymbolInfo.ReturnType : null;
+
+        List<string> BuildBodyCode(string instancePrefix, string? returnType)
         {
-            return innerBodyCreationDelegates.GetCallMethodCode(methodSymbolInfo).BuildCode(instancePrefix, parameters);
+            return innerBodyCreationDelegates.GetCallMethodCode(methodSymbolInfo)
+                .BuildCode(instancePrefix, parameters, returnType);
         }
 
-        return new BuilderMethod(methodName, methodSymbolInfo.GenericInfo, parameters, BuildBodyCode);
+        return new BuilderMethod(
+            methodName,
+            methodSymbolInfo.GenericInfo,
+            parameters,
+            returnTypeToRespect,
+            BuildBodyCode);
     }
 }

src/M31.FluentApi.Generator/CodeGeneration/CodeBoardActors/InnerBodyGeneration/InnerBodyGenerator.cs renamed to src/M31.FluentApi.Generator/CodeGeneration/CodeBoardActors/InnerBodyGeneration/InnerBodyCreator.cs

@@ -2,12 +2,12 @@
 
 namespace M31.FluentApi.Generator.CodeGeneration.CodeBoardActors.InnerBodyGeneration;
 
-internal class InnerBodyGenerator : ICodeBoardActor
+internal class InnerBodyCreator : ICodeBoardActor
 {
     public void Modify(CodeBoard codeBoard)
     {
-        LineForMemberGenerator lineForMemberGenerator = new LineForMemberGenerator(codeBoard);
-        LineForMethodGenerator lineForMethodGenerator = new LineForMethodGenerator(codeBoard);
+        InnerBodyForMemberGenerator innerBodyForMemberGenerator = new InnerBodyForMemberGenerator(codeBoard);
+        InnerBodyForMethodGenerator innerBodyForMethodGenerator = new InnerBodyForMethodGenerator(codeBoard);
 
         foreach (FluentApiSymbolInfo symbolInfo in codeBoard.FluentApiInfos.Select(m => m.SymbolInfo))
         {
@@ -19,19 +19,19 @@ public void Modify(CodeBoard codeBoard)
             switch (symbolInfo)
             {
                 case MemberSymbolInfo memberInfo:
-                    lineForMemberGenerator.GenerateLine(memberInfo);
+                    innerBodyForMemberGenerator.GenerateInnerBody(memberInfo);
                     break;
 
                 case MethodSymbolInfo methodInfo:
-                    lineForMethodGenerator.GenerateLine(methodInfo);
+                    innerBodyForMethodGenerator.GenerateInnerBody(methodInfo);
                     break;
 
                 default:
                     throw new ArgumentException($"Unknown symbol info type: {symbolInfo.GetType()}");
             }
         }
 
-        if (lineForMemberGenerator.ReflectionRequired || lineForMethodGenerator.ReflectionRequired)
+        if (innerBodyForMemberGenerator.ReflectionRequired || innerBodyForMethodGenerator.ReflectionRequired)
         {
             ImportReflectionNamespace(codeBoard);
         }