feat: builder from existing instance (#53)

* chore: Employee2 generated code example

* feat: constructor with instance

* chore: expected results with constructor with instance

* feat: FromExistingInterface

* feat: FromExistingInterface

* chore: adapt tests for any step interface

* feat: FromExistingMethodGenerator

* chore: overwrite tests with new generation

* test: CanCreateThreeMemberClassFromExisting

* docs(01_Basics): explain FromExisting

* docs(README.md): add paragraph about `FromExisting`

* docs(01_Basics): clarify FromExisting

* chore: bump nuget version

* docs(README): update doc comments image

Author: m31coding

README.md

@@ -42,7 +42,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="2.0.0" PrivateAssets="all"/>
+<PackageReference Include="M31.FluentApi" Version="2.1.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:
@@ -502,6 +502,18 @@ To simplify adding documentation comments, a code action is available to generat
 ![doc-comments-action](https://raw.githubusercontent.com/m31coding/M31.FluentAPI/main/media/create-doc-comments-action.png)
 
 For reference, you can view the documented version of the `Student` class in [DocumentedStudent.cs](src/M31.FluentApi.Tests/CodeGeneration/TestClasses/DocumentedStudentClass/DocumentedStudent.cs). The corresponding generated code is located in [DocumentedStudent.g.cs](src/M31.FluentApi.Tests/CodeGeneration/TestClasses/DocumentedStudentClass/CreateDocumentedStudent.g.cs)
+    
+
+### Modifying an existing instance
+
+The static `FromExisting` method can be used to modify an existing instance:
+
+```cs
+Student student1 = CreateStudent.WithFirstName("Alice").WithLastName("King");
+Student student2 = CreateStudent.FromExisting(student1).WithLastName("Queen");
+```
+
+After calling `FromExisting`, the builder can continue from any step. To avoid mutating the original instance, create a copy constructor on the `Student` class and pass a copy to the `FromExisting` method.
 
 
 ### Lambda pattern
@@ -592,4 +604,4 @@ In particular, if your IDE visually indicates that there are errors in your code
 
 This library is free. If you find it valuable and wish to express your support, please leave a star. You are kindly invited to contribute. If you see the possibility for enhancement, please create a GitHub issue and you will receive timely feedback.
 
-Happy coding!
+Happy coding!

media/create-doc-comments-action.png

@@ -23,6 +23,7 @@ public void Modify(CodeBoard codeBoard)
 
         List<Interface> interfaces = new List<Interface>(builderStepMethods.Interfaces.Count);
         interfaces.Add(CreateInitialStepInterface(builderStepMethods, codeBoard));
+        interfaces.Add(CreateFromAnyStepInterface(builderStepMethods, codeBoard));
 
         foreach (BuilderInterface builderInterface in builderStepMethods.Interfaces)
         {
@@ -92,6 +93,19 @@ private Interface CreateInitialStepInterface(BuilderStepMethods builderStepMetho
         return initialStepInterface;
     }
 
+    private Interface CreateFromAnyStepInterface(BuilderStepMethods builderStepMethods, CodeBoard codeBoard)
+    {
+        Interface fromExistingInterface =
+            new Interface(codeBoard.Info.DefaultAccessModifier, codeBoard.Info.FromExistingInterfaceName);
+
+        foreach (BuilderInterface @interface in builderStepMethods.Interfaces)
+        {
+            fromExistingInterface.AddBaseInterface(@interface.InterfaceName);
+        }
+
+        return fromExistingInterface;
+    }
+
     private void AddInterfacesToBuilderClass(List<Interface> interfaces, Class builderClass, string prefix)
     {
         foreach (Interface @interface in interfaces)

src/M31.FluentApi.Generator/CodeGeneration/CodeBoardActors/BuilderMethodsGeneration/BuilderGenerator.cs

@@ -8,11 +8,17 @@ namespace M31.FluentApi.Generator.CodeGeneration.CodeBoardActors;
 internal class ConstructorGenerator : ICodeBoardActor
 {
     public void Modify(CodeBoard codeBoard)
+    {
+        CreateParameterlessConstructor(codeBoard);
+        CreateConstructorWithInstanceParameter(codeBoard);
+    }
+
+    private static void CreateParameterlessConstructor(CodeBoard codeBoard)
     {
         string instanceName = codeBoard.Info.ClassInstanceName;
         string classNameWithTypeParameters = codeBoard.Info.FluentApiClassNameWithTypeParameters;
 
-        Method constructor = CreateConstructor(codeBoard.Info.BuilderClassName);
+        Method constructor = CreateParameterlessConstructorMethod(codeBoard.Info.BuilderClassName);
         ConstructorInfo constructorInfo = codeBoard.Info.FluentApiTypeConstructorInfo;
 
         if (codeBoard.Info.FluentApiTypeConstructorInfo.ConstructorIsNonPublic)
@@ -59,7 +65,17 @@ public void Modify(CodeBoard codeBoard)
             constructor.AppendBodyLine(codeBuilder.ToString());
         }
 
-        codeBoard.Constructor = constructor;
+        codeBoard.BuilderClass.AddMethod(constructor);
+    }
+
+    private static void CreateConstructorWithInstanceParameter(CodeBoard codeBoard)
+    {
+        Method constructor = CreateConstructorWithInstanceParameterMethod(codeBoard.Info);
+
+        CodeBuilder codeBuilder = new CodeBuilder(codeBoard.NewLineString);
+        codeBuilder.Append($"this.{codeBoard.Info.ClassInstanceName} = {codeBoard.Info.ClassInstanceName};");
+        constructor.AppendBodyLine(codeBuilder.ToString());
+
         codeBoard.BuilderClass.AddMethod(constructor);
     }
 
@@ -112,11 +128,22 @@ private static string CreateArgument(
         return "default!";
     }
 
-    private static Method CreateConstructor(string builderClassName)
+    private static Method CreateParameterlessConstructorMethod(string builderClassName)
     {
         // private CreateStudent()
         MethodSignature signature = MethodSignature.CreateConstructorSignature(builderClassName);
         signature.AddModifiers("private");
         return new Method(signature);
     }
+
+    private static Method CreateConstructorWithInstanceParameterMethod(
+        BuilderAndTargetInfo info)
+    {
+        // private CreateStudent(Student student)
+        MethodSignature signature = MethodSignature.CreateConstructorSignature(info.BuilderClassName);
+        Parameter parameter = new Parameter(info.FluentApiClassNameWithTypeParameters, info.ClassInstanceName);
+        signature.AddParameter(parameter);
+        signature.AddModifiers("private");
+        return new Method(signature);
+    }
 }

src/M31.FluentApi.Generator/CodeGeneration/CodeBoardActors/ConstructorGenerator.cs

@@ -0,0 +1,32 @@
+using M31.FluentApi.Generator.CodeBuilding;
+using M31.FluentApi.Generator.CodeGeneration.CodeBoardElements;
+
+namespace M31.FluentApi.Generator.CodeGeneration.CodeBoardActors;
+
+internal class FromExistingMethodGenerator : ICodeBoardActor
+{
+    public void Modify(CodeBoard codeBoard)
+    {
+        // public static ICreateStudentFromAnyStep FromExisting(Student student)
+        // {
+        //     return new CreateStudent(student);
+        // }
+        BuilderAndTargetInfo info = codeBoard.Info;
+        string methodName = "FromExisting";
+        MethodSignature methodSignature = MethodSignature.Create(
+            info.FromExistingInterfaceName,
+            methodName,
+            null,
+            false);
+        methodSignature.AddModifiers(info.DefaultAccessModifier, "static");
+        Parameter parameter = new Parameter(
+            info.FluentApiClassNameWithTypeParameters,
+            info.ClassInstanceName);
+        methodSignature.AddParameter(parameter);
+        Method method = new Method(methodSignature);
+        string parameterListInAngleBrackets = info.GenericInfo?.ParameterListInAngleBrackets ?? string.Empty;
+        method.AppendBodyLine(
+            $"return new {info.BuilderClassName}{parameterListInAngleBrackets}({info.ClassInstanceName});");
+        codeBoard.BuilderClass.AddMethod(method);
+    }
+}

src/M31.FluentApi.Generator/CodeGeneration/CodeBoardActors/FromExistingMethodGenerator.cs

@@ -30,6 +30,7 @@ internal BuilderAndTargetInfo(
         BuilderInstanceName = builderClassName.FirstCharToLower();
         ClassInstanceName = fluentApiClassName.FirstCharToLower();
         InitialStepInterfaceName = $"I{builderClassName}";
+        FromExistingInterfaceName = $"I{builderClassName}FromExisting";
     }
 
     internal string? Namespace { get; }
@@ -45,4 +46,5 @@ internal BuilderAndTargetInfo(
     internal string BuilderInstanceName { get; }
     internal string ClassInstanceName { get; }
     internal string InitialStepInterfaceName { get; }
+    internal string FromExistingInterfaceName { get; }
 }

src/M31.FluentApi.Generator/CodeGeneration/CodeBoardElements/BuilderAndTargetInfo.cs

@@ -30,8 +30,6 @@ private CodeBoard(
         Info = builderAndTargetInfo;
         CodeFile = codeFile;
         BuilderClass = builderClass;
-        Constructor = null;
-        StaticConstructor = null;
         InnerBodyCreationDelegates = new InnerBodyCreationDelegates();
         TransformedComments = new TransformedComments();
         GroupsToMethods = new Dictionary<FluentApiInfoGroup, BuilderMethods>();
@@ -48,8 +46,6 @@ private CodeBoard(
     internal BuilderAndTargetInfo Info { get; }
     internal CodeFile CodeFile { get; }
     internal Class BuilderClass { get; }
-    internal Method? Constructor { get; set; }
-    internal Method? StaticConstructor { get; set; }
     internal InnerBodyCreationDelegates InnerBodyCreationDelegates { get; }
     internal TransformedComments TransformedComments { get; }
     internal Dictionary<FluentApiInfoGroup, BuilderMethods> GroupsToMethods { get; }

src/M31.FluentApi.Generator/CodeGeneration/CodeBoardElements/CodeBoard.cs

@@ -26,6 +26,7 @@ internal static CodeGeneratorResult GenerateCode(FluentApiClassInfo classInfo, C
             new ForkCreator(),
             new DuplicateMethodsChecker(),
             new InitialStepMethodGenerator(),
+            new FromExistingMethodGenerator(),
             new BuilderGenerator(),
         };
 

src/M31.FluentApi.Generator/CodeGeneration/CodeGenerator.cs

@@ -11,7 +11,7 @@
     <GenerateDocumentationFile>true</GenerateDocumentationFile>
     <GeneratePackageOnBuild>true</GeneratePackageOnBuild>
     <SuppressDependenciesWhenPacking>true</SuppressDependenciesWhenPacking>
-    <PackageVersion>2.0.0</PackageVersion>
+    <PackageVersion>2.1.0</PackageVersion>
     <Authors>Kevin Schaal</Authors>
     <Description>The generator package for M31.FluentAPI. Don't install this package explicitly, install M31.FluentAPI instead.</Description>
     <PackageTags>fluentapi fluentbuilder fluentinterface fluentdesign fluent codegeneration</PackageTags>

src/M31.FluentApi.Generator/M31.FluentApi.Generator.csproj

@@ -8,8 +8,14 @@ namespace BasicExample
 {
     /* Generates a builder class with name CreateStudent and methods WithFirstName and WithLastName. The methods have to
        be called in the specified order, WithFirstName (builder step 0) has to be called before WithLastName (builder
-       step 1). As shown in the usage examples below, a student can be either created by calling the static
-       WithFirstName method on the CreateStudent class, or by first creating a new builder instance.
+       step 1).
+       As shown in the usage examples below, a student can be created by calling the static WithFirstName
+       method on the CreateStudent class.
+       Alternatively, an existing Student can be passed to the static FromExisting method. After calling FromExisting,
+       the builder can continue from any step. The FromExisting method mutates the passed instance, and the last name
+       is set to "Queen".
+       The InitialStep method can be used to create a builder instance without creating a student. This is useful for
+       advanced use cases such as the lambda pattern, as described in the README.md.
        Although I use classes with properties in all examples of this file, the FluentApi attribute can also be applied
        to structs and records, and the FluentMember attribute also works with fields. */
 
@@ -29,8 +35,10 @@ public static void UseTheGeneratedFluentApi()
         {
             Student student1 = CreateStudent.WithFirstName("Alice").WithLastName("King");
 
+            Student student2 = CreateStudent.FromExisting(student1).WithLastName("Queen");
+
             CreateStudent.ICreateStudent createStudent = CreateStudent.InitialStep();
-            Student student2 = createStudent.WithFirstName("Bob").WithLastName("Bishop");
+            Student student3 = createStudent.WithFirstName("Bob").WithLastName("Bishop");
         }
     }
 }