feat: FluentLambda and InitialStep (#17)

* fix(Readme): add media from githubusercontent

* feat: add FluentLambdaAttribute

* test: add test class FluentLambdaClass

* feat: explicit interface implementations for the generated builder

* refactor(MethodSignature): rename isStandAlone to isSignatureForInterface

* fix(MethodSignature): no default parameter values for explicit interface implementations

* test: rerun tests and write results with explicit interface implementations

* refactor(MethodSignature): don't erase values in copy constructor

* test: EmptyClass

* feat: implement InitialStep method and test with OneMemberClass, TwoMemberClass and ThreeMemberClass

* fix(TestDataProvider): remove single test filter method

* fix: GenericClassWithConstraints test

* test: rerun tests and write generated code as expected code

* fix: names of test classes

* fix(Readme): typo

* feat(DuplicateMethodsChecker): check for reserved method names

* chore: add M31FA021 (reserved method name) to shipped analyzer releases

* test: ThreePrivateMembersClass

* test: add more code generation execution tests

* test: add CanExecutePrivateConstructorClass

* feat(FluentLambda): make FluentLambdaClass test work

* feat(FluentLambda): FluentLambdaMemberWithoutFluentApi diagnostic

* test: CanDetectFluentLambdaMemberWithoutFluentApiClass

* test: CanExecuteFluentLambdaClass

* test: FluentLambdaSingleStepClass and CanExecuteFluentLambdaSingleStepClass

* test: FluentLambdaNullablePropertyClass

* test: add failing test FluentLambdaRecursiveClass

* test(FluentLambdaRecursiveClass): add name property

* refactor(BuilderClassFields): single GetNewFieldName method

* refactor(BuilderClassFields): rename to ReservedVariableNames

* feat: make test FluentLambdaRecursiveClass work

* test: CanExecuteFluentLambdaRecursiveClass

* test: add failing test TryBreakFluentApiClass1

* fix: make test TryBreakFluentApiClass1 work

* test: TryBreakFluentApiClass2

* test(FluentLambdaRecursiveClass): add name property

* fix: don't use builder type prefix for info fields in the constructor

* test: rerun tests and write results as expected results

* test: FluentLambdaClassInDifferentNamespace

* fix: address resharper warnings

* fix: address more resharper warnings

* fix: failing tests due to resharper annotations

* fix: remove obsolete comment

* chore: optimize description and package tags

* improve(ExampleProject): add person examples to Program.cs

* fix: nullable private method property

* improve(ExampleProject): add HashCode class

* improve(ExampleProject): add DockerFile example

* fix(ExampleProject): rename file

* docs(Readme): add FluentLambda

* fix: InitialStep for empty class

* fix: remove obsolete NoMember class

* improve: add city to FluentLambda tests

* fix(TestDataProvider): remove NoMemberClass

* fix(CodeGenerationTests): adjust for new Address model

* improve(FluentLambda): also generate normal member builder method

* fix(FluentLambdaClassInDifferentNamespace): take normal builder method into account

* improve(Storybook): add FluentLambda

* docs(Readme): minor changes

* improve(Storybook): revise texts

* chore: increase nuget versions to 1.4.0

Author: m31coding

README.md

@@ -1,6 +1,6 @@
 # Fluent APIs in C#
 
-![M31.FluentApi logo](media/fluent-api-logo-256.jpg)
+![M31.FluentApi logo](https://raw.githubusercontent.com/m31coding/M31.FluentAPI/main/media/fluent-api-logo-256.jpg)
 
 Everybody wants to use fluent APIs but writing them is tedious. With this library providing fluent APIs for your classes becomes a breeze. Simply annotate them with attributes and the source code for the fluent API will be generated. The fluent API library leverages incremental source code generation at development time and your IDE will offer you the corresponding code completion immediately.
 
@@ -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.3.0" PrivateAssets="all"/>
+<PackageReference Include="M31.FluentApi" Version="1.4.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:
@@ -46,8 +46,16 @@ If you use this library for the first time I recommend that you read the storybo
 - [01 Basics](src/M31.FluentApi.Storybook/01_Basics.cs)
 - [02 Control attributes](src/M31.FluentApi.Storybook/02_ControlAttributes.cs)
 
+Moreover, you may find several Fluent API examples and their [usage](src/ExampleProject/Program.cs) in the example project:
 
-Here is the full example from the introduction to the basics:
+- [Student](src/ExampleProject/Student.cs)
+- [Person](src/ExampleProject/Person.cs)
+- [HashCode](src/ExampleProject/HashCode.cs)
+- [Node](src/ExampleProject/Node.cs)
+- [DockerFile](src/ExampleProject/DockerFile.cs)
+- ...
+
+Here is an example from the introduction to the basics:
 
 ```cs
 [FluentApi]
@@ -89,15 +97,15 @@ public class Student
  }
 ```
 
-![fluent-api-usage](media/fluent-api.gif)
+![fluent-api-usage](https://raw.githubusercontent.com/m31coding/M31.FluentAPI/main/media/fluent-api.gif)
 
 You may have a look at the generated code for this example: [CreateStudent.g.cs](src/M31.FluentApi.Tests/CodeGeneration/TestClasses/StudentClass/CreateStudent.g.cs). Note that if you use private members or properties with a private set accessor, as it is the case in this example, the generated code will use reflection to set the properties.
 
 ## Attributes
 
 The attributes `FluentApi` and `FluentMember` are all you need in order to get started. 
 
-The attributes `FluentPredicate` and `FluentCollection` can be used instead of a `FluentMember` attribute if the decorated member is a boolean or a collection, respectively. 
+The attributes `FluentPredicate`, `FluentCollection`, and `FluentLambda` can be used instead of the `FluentMember` attribute if the decorated member is a boolean, a collection, or has its own Fluent API, respectively. 
 
 `FluentDefault` and `FluentNullable` can be used in combination with these attributes to set a default value or null, respectively. 
 
@@ -118,8 +126,17 @@ Use this attribute for your class / struct / record. The optional parameter allo
 public class Student
 ```
 
+You can create instances by statically accessing the generated `CreateStudent` class:
+
+```cs
+Student alice = CreateStudent.WithFirstName("Alice")...
+```
+
+Alternatively, you can call `InitialStep` to get a new builder instance:
+
 ```cs
-Student alice = CreateStudent...
+ICreateStudent createStudent = CreateStudent.InitialStep();
+Student alice = createStudent.WithFirstName("Alice")...
 ```
 
 ### FluentMember
@@ -160,7 +177,7 @@ public string LastName { get; private set; }
 FluentPredicate(int builderStep, string method = "{Name}", string negatedMethod = "Not{Name}")
 ```
 
-Can be used instead of a `FluentMember` attribute if the decorated member is of type `bool`. This attribute generates three methods, one for setting the value of the member to `true`, one for setting it to `false`, and one for passing the boolean value.
+Can be used instead of the `FluentMember` attribute if the decorated member is of type `bool`. This attribute generates three methods, one for setting the value of the member to `true`, one for setting it to `false`, and one for passing the boolean value.
 
 ```cs
 [FluentPredicate(4, "WhoIsHappy", "WhoIsSad")]
@@ -185,21 +202,40 @@ FluentCollection(
     string withZeroItems = "WithZero{Name}")
 ```
 
-Can be used instead of a `FluentMember` attribute if the decorated member is a collection. This attribute generates methods for setting multiple items, one item and zero items. The supported collection types can be seen in the source file [CollectionInference.cs](src/M31.FluentApi.Generator/SourceGenerators/Collections/CollectionInference.cs). 
+Can be used instead of the `FluentMember` attribute if the decorated member is a collection. This attribute generates methods for setting multiple items, one item and zero items. The supported collection types can be seen in the source file [CollectionInference.cs](src/M31.FluentApi.Generator/SourceGenerators/Collections/CollectionInference.cs). 
 
 ```cs
 [FluentCollection(5, "Friend", "WhoseFriendsAre", "WhoseFriendIs", "WhoHasNoFriends")]
 public IReadOnlyCollection<string> Friends { get; private set; }
 ```
 
 ```cs
-....WhoseFriendsAre(new string[] { "Bob", "Carol", "Eve" })...
+...WhoseFriendsAre(new string[] { "Bob", "Carol", "Eve" })...
 ...WhoseFriendsAre("Bob", "Carol", "Eve")...
 ...WhoseFriendIs("Alice")...
 ...WhoHasNoFriends()...
 ```
 
 
+### FluentLambda
+
+```cs
+FluentLambda(int builderStep, string method = "With{Name}")
+```
+
+Can be used instead of the `FluentMember` attribute if the decorated member has its own Fluent API. Generates an additional builder method that accepts a lambda expression for creating the target field or property.
+        
+```cs
+[FluentLambda(1)]
+public Address Address { get; private set; }
+```
+
+```cs
+...WithAddress(new Address("23", "Market Street", "San Francisco"))...
+...WithAddress(a => a.WithHouseNumber("23").WithStreet("Market Street").InCity("San Francisco"))...
+```
+   
+
 ### FluentDefault
 
 ```cs
@@ -328,6 +364,9 @@ string serialized = ...ToJson();
 ```
 
 
+## Miscellaneous
+
+
 ### 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:
@@ -352,9 +391,28 @@ private void BornOn(DateOnly dateOfBirth)
 ```
 
 
+### Lambda pattern
+                       
+Instances of Fluent API classes can be created and passed into methods of other classes using the lambda pattern. For example, given a `University` class that needs to be augmented with an `AddStudent` method, the following code demonstrates the lambda pattern:
+
+```cs
+public void AddStudent(Func<CreateStudent.ICreateStudent, Student> createStudent)
+{
+    Student student = createStudent(CreateStudent.InitialStep());
+    students.Add(student);
+}
+```
+
+```cs
+university.AddStudent(s => s.Named("Alice", "King").OfAge(22)...);
+```
+
+Note that if you want to set a single field or property on a Fluent API class, you can instead use the `FluentLambda` attribute.
+
+
 ## Problems with the IDE
 
-As of 2023 code generation with Roslyn is still a relatively new feature but is already supported quite well in Visual Studio and Rider. Since code generation is potentially triggered with every single key stroke, there are sometimes situations where the code completion index of the IDE does not keep up with all the changes.
+Since code generation is potentially triggered with every single key stroke, there are sometimes situations where the code completion index of the IDE does not keep up with all the changes.
 
 In particular, if your IDE visually indicates that there are errors in your code but it compiles and runs just fine, try the following things:
 

src/ExampleProject/DockerFile.cs

@@ -0,0 +1,69 @@
+// Non-nullable member is uninitialized
+#pragma warning disable CS8618
+// ReSharper disable All
+
+// Example from https://mitesh1612.github.io/blog/2021/08/11/how-to-design-fluent-api.
+
+using System.Text;
+using M31.FluentApi.Attributes;
+
+namespace ExampleProject;
+
+[FluentApi]
+public class DockerFile
+{
+    private readonly StringBuilder content;
+
+    private DockerFile()
+    {
+        content = new StringBuilder();
+    }
+
+    [FluentMethod(0)]
+    private void FromImage(string imageName)
+    {
+        content.AppendLine($"FROM {imageName}");
+    }
+
+    [FluentMethod(1)]
+    [FluentContinueWith(1)]
+    private void CopyFiles(string source, string destination)
+    {
+        content.AppendLine($"COPY {source} {destination}");
+    }
+
+    [FluentMethod(1)]
+    [FluentContinueWith(1)]
+    private void RunCommand(string command)
+    {
+        content.AppendLine($"RUN {command}");
+    }
+
+    [FluentMethod(1)]
+    [FluentContinueWith(1)]
+    private void ExposePort(int port)
+    {
+        content.AppendLine($"EXPOSE {port}");
+    }
+
+    [FluentMethod(1)]
+    [FluentContinueWith(1)]
+    private void WithEnvironmentVariable(string variableName, string variableValue)
+    {
+        content.AppendLine($"ENV {variableName}={variableValue}");
+    }
+
+    [FluentMethod(1)]
+    private void WithCommand(string command)
+    {
+        var commandList = command.Split(" ");
+        content.Append("CMD [ ");
+        content.Append(string.Join(", ", commandList.Select(c => $"\"{c}\"")));
+        content.Append(']');
+    }
+
+    public override string ToString()
+    {
+        return content.ToString();
+    }
+}

src/ExampleProject/HashCode.cs

@@ -0,0 +1,95 @@
+using M31.FluentApi.Attributes;
+
+namespace ExampleProject;
+
+[FluentApi]
+public struct HashCode
+{
+    private int hash;
+
+    public HashCode()
+    {
+        hash = 17;
+    }
+
+    [FluentMethod(0)]
+    [FluentContinueWith(0)]
+    public void Add<T>(T value)
+    {
+        unchecked
+        {
+            hash = hash * 23 + value?.GetHashCode() ?? 0;
+        }
+    }
+
+    [FluentMethod(0)]
+    [FluentContinueWith(0)]
+    public void Add<T1, T2>(T1 value1, T2 value2)
+    {
+        unchecked
+        {
+            hash = hash * 23 + value1?.GetHashCode() ?? 0;
+            hash = hash * 23 + value2?.GetHashCode() ?? 0;
+        }
+    }
+
+    [FluentMethod(0)]
+    [FluentContinueWith(0)]
+    public void Add<T1, T2, T3>(T1 value1, T2 value2, T3 value3)
+    {
+        unchecked
+        {
+            hash = hash * 23 + value1?.GetHashCode() ?? 0;
+            hash = hash * 23 + value2?.GetHashCode() ?? 0;
+            hash = hash * 23 + value3?.GetHashCode() ?? 0;
+        }
+    }
+
+    [FluentMethod(0)]
+    [FluentContinueWith(0)]
+    public void Add<T1, T2, T3, T4>(T1 value1, T2 value2, T3 value3, T4 value4)
+    {
+        unchecked
+        {
+            hash = hash * 23 + value1?.GetHashCode() ?? 0;
+            hash = hash * 23 + value2?.GetHashCode() ?? 0;
+            hash = hash * 23 + value3?.GetHashCode() ?? 0;
+            hash = hash * 23 + value4?.GetHashCode() ?? 0;
+        }
+    }
+
+    [FluentMethod(0)]
+    [FluentContinueWith(0)]
+    public void Add<T1, T2, T3, T4, T5>(T1 value1, T2 value2, T3 value3, T4 value4, T5 value5)
+    {
+        unchecked
+        {
+            hash = hash * 23 + value1?.GetHashCode() ?? 0;
+            hash = hash * 23 + value2?.GetHashCode() ?? 0;
+            hash = hash * 23 + value3?.GetHashCode() ?? 0;
+            hash = hash * 23 + value4?.GetHashCode() ?? 0;
+            hash = hash * 23 + value5?.GetHashCode() ?? 0;
+        }
+    }
+
+    [FluentMethod(0)]
+    [FluentContinueWith(0)]
+    public void AddSequence<T>(IEnumerable<T> items)
+    {
+        unchecked
+        {
+            foreach (T item in items)
+            {
+                hash = hash * 23 + item?.GetHashCode() ?? 0;
+            }
+
+        }
+    }
+
+    [FluentMethod(0)]
+    [FluentReturn]
+    public int Value()
+    {
+        return hash;
+    }
+}