Merge pull request #14 from robdmoore/listbuilder-tidy-up

Added breaking changes file and tidied up list builder classes

Author: robdmoore

BREAKING_CHANGES.md

@@ -0,0 +1,40 @@
+NTestDataBuilder Breaking Changes
+=================================
+
+Version 2.0.0
+-------------
+
+The way that lists are generated no longer uses NBuilder - the new syntax is backwards compatible with NBuilder except that the namespace you need to include is different. You can also refactor your list generation to be a lot more terse, but that is optional. Any `BuildList` extension methods you created will now need to be deleted since they are no longer needed.
+
+### Reason
+In order to support a new, much terser syntax for generating lists we rewrote the list generation code ourselves. You can now do this:
+
+```c#
+	var customers = CustomerBuilder.CreateListOfSize(3)
+		.TheFirst(1).WithFirstName("Robert")
+		.TheLast(1).WithEmail("[email protected]")
+		.BuildList();
+```
+
+That's instead of this syntax (which still works as well):
+
+```c#
+	var customers = CustomerBuilder.CreateListOfSize(3)
+		.TheFirst(1).With(b => b.WithFirstName("Robert"))
+		.TheLast(1).With(b => b.WithEmail("[email protected]"))
+		.BuildList();
+```
+
+You also no longer need a custom extension method for the `BuildList` method so you will need to delete any of these that you have created. If you don't use NBuilder's features outside of the list generation you may uninstall the NBuilder package.
+
+### Fix
+
+Simply add the following to the files that generate lists of builders and the existing syntax should work:
+
+```
+using NTestDataBuilder.Lists;
+```
+
+If you uninstall the NBuilder package then you will need to remove the using statements for that library too.
+
+Also, remove any `BuildList` extension methods you created.

NTestDataBuilder.sln

@@ -1,14 +1,15 @@
 
 Microsoft Visual Studio Solution File, Format Version 12.00
 # Visual Studio 2013
-VisualStudioVersion = 12.0.30501.0
+VisualStudioVersion = 12.0.30723.0
 MinimumVisualStudioVersion = 10.0.40219.1
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "NTestDataBuilder", "NTestDataBuilder\NTestDataBuilder.csproj", "{01E4EE61-AB1A-4177-8B6C-D50205D167A9}"
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "NTestDataBuilder.Tests", "NTestDataBuilder.Tests\NTestDataBuilder.Tests.csproj", "{DC49CE57-CB3F-487D-83DC-6A4E78CB908C}"
 EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Solution Items", "Solution Items", "{BC8508D1-6FCB-46B2-9C14-F41F6AD76B09}"
 	ProjectSection(SolutionItems) = preProject
+		BREAKING_CHANGES.md = BREAKING_CHANGES.md
 		LICENSE = LICENSE
 		logo.png = logo.png
 		README.md = README.md

NTestDataBuilder/Lists/EnsureAllMethodsVirtual.cs

@@ -0,0 +1,26 @@
+using System;
+using System.Linq;
+using System.Reflection;
+using Castle.DynamicProxy;
+
+namespace NTestDataBuilder.Lists
+{
+    internal class EnsureAllMethodsVirtual : IProxyGenerationHook
+    {
+        public void MethodsInspected()
+        {
+        }
+
+        public void NonProxyableMemberNotification(Type type, MemberInfo memberInfo)
+        {
+            if (new[]{"get_Any", "Build", "AsProxy", "Get", "GetOrDefault", "Set", "Has", "get_ListBuilder", "set_ListBuilder"}.Contains(memberInfo.Name))
+                return;
+            throw new InvalidOperationException(string.Format("Tried to build a list with a builder who has non-virtual method. Please make {0} on type {1} virtual.", memberInfo.Name, type.Name));
+        }
+
+        public bool ShouldInterceptMethod(Type type, MethodInfo methodInfo)
+        {
+            return true;
+        }
+    }
+}

NTestDataBuilder/Lists/ListBuilder.cs

@@ -1,96 +1,15 @@
 using System;
 using System.Collections.Generic;
 using System.Linq;
-using System.Reflection;
 using Castle.DynamicProxy;
 
 namespace NTestDataBuilder.Lists
 {
-    public static class ListBuilderGenerator
-    {
-        static ListBuilderGenerator()
-        {
-            Generator = new ProxyGenerator(true);
-        }
-
-        public static ProxyGenerator Generator { get; private set; } 
-    }
-
-    public static class ListBuilderExtensions
-    {
-        public static TBuilder TheFirst<TObject, TBuilder>(this TestDataBuilder<TObject, TBuilder> b, int howMany)
-            where TObject : class
-            where TBuilder : TestDataBuilder<TObject, TBuilder>, new()
-        {
-            return b.ListBuilder.TheFirst(howMany);
-        }
-
-        public static TBuilder TheNext<TObject, TBuilder>(this TestDataBuilder<TObject, TBuilder> b, int howMany)
-            where TObject : class
-            where TBuilder : TestDataBuilder<TObject, TBuilder>, new()
-        {
-            return b.ListBuilder.TheNext(howMany);
-        }
-
-        public static TBuilder TheLast<TObject, TBuilder>(this TestDataBuilder<TObject, TBuilder> b, int howMany)
-            where TObject : class
-            where TBuilder : TestDataBuilder<TObject, TBuilder>, new()
-        {
-            return b.ListBuilder.TheLast(howMany);
-        }
-
-        public static TBuilder ThePrevious<TObject, TBuilder>(this TestDataBuilder<TObject, TBuilder> b, int howMany)
-            where TObject : class
-            where TBuilder : TestDataBuilder<TObject, TBuilder>, new()
-        {
-            return b.ListBuilder.ThePrevious(howMany);
-        }
-
-        public static TBuilder All<TObject, TBuilder>(this TestDataBuilder<TObject, TBuilder> b)
-            where TObject : class
-            where TBuilder : TestDataBuilder<TObject, TBuilder>, new()
-        {
-            return b.ListBuilder.All();
-        }
-
-        public static ListBuilder<TObject, TBuilder> With<TObject, TBuilder>(this TestDataBuilder<TObject, TBuilder> b, Func<TBuilder, TBuilder> modifier)
-            where TObject : class
-            where TBuilder : TestDataBuilder<TObject, TBuilder>, new()
-        {
-            return b.ListBuilder.With(modifier);
-        }
-
-        public static IList<TObject> BuildList<TObject, TBuilder>(this TestDataBuilder<TObject, TBuilder> b)
-            where TObject : class
-            where TBuilder : TestDataBuilder<TObject, TBuilder>, new()
-        {
-            return b.ListBuilder.BuildList();
-        }
-    }
-
-    public class ListBuilderInterceptor<TObject, TBuilder> : IInterceptor
-        where TBuilder : TestDataBuilder<TObject, TBuilder>, new()
-        where TObject : class
-    {
-        private readonly ListBuilder<TObject, TBuilder> _builder;
-
-        public ListBuilderInterceptor(ListBuilder<TObject, TBuilder> builder)
-        {
-            _builder = builder;
-        }
-
-        public void Intercept(IInvocation invocation)
-        {
-            if (invocation.Method.ReturnType != typeof (TBuilder))
-            {
-                throw new InvalidOperationException("Non-fluent builder method invoked while creating a list of builders: " + invocation.Method.Name);
-            }
-
-            _builder.Execute(invocation);
-            invocation.ReturnValue = _builder.BuilderProxy;
-        }
-    }
-
+    /// <summary>
+    /// Class that builds lists of objects by proxying a list of object builders.
+    /// </summary>
+    /// <typeparam name="TObject">The type of object being built</typeparam>
+    /// <typeparam name="TBuilder">The type of builder that is building the object</typeparam>
     public class ListBuilder<TObject, TBuilder>
         where TBuilder : TestDataBuilder<TObject, TBuilder>, new()
         where TObject : class
@@ -99,7 +18,7 @@ public class ListBuilder<TObject, TBuilder>
         private int _count = 0;
         private readonly List<TBuilder> _list;
 
-        public ListBuilder(int size)
+        internal ListBuilder(int size)
         {
             BuilderProxy = (TBuilder) ListBuilderGenerator.Generator
                 .CreateClassProxy(typeof (TBuilder), new ProxyGenerationOptions(new EnsureAllMethodsVirtual()), new ListBuilderInterceptor<TObject, TBuilder>(this));
@@ -109,43 +28,74 @@ public ListBuilder(int size)
                 _list.Add(new TBuilder());
         }
 
-        public TBuilder BuilderProxy { get; private set; }
+        internal TBuilder BuilderProxy { get; private set; }
 
+        /// <summary>
+        /// Will target the first x objects (as specified) for subsequent builder calls (or .With call).
+        /// You can combine this with .TheNext(y) to target the next y after the first x.
+        /// </summary>
+        /// <param name="howMany">The first {howMany} objects should be targeted?</param>
+        /// <returns>The builder proxy so that calls can continue to be chained</returns>
         public TBuilder TheFirst(int howMany)
         {
             _start = 0;
             _count = howMany;
             return BuilderProxy;
         }
 
+        /// <summary>
+        /// Will target the next x objects (as specified) for subsequent builder calls (or .With call).
+        /// </summary>
+        /// <param name="howMany">The next {howMany} objects should be targeted?</param>
+        /// <returns>The builder proxy so that calls can continue to be chained</returns>
         public TBuilder TheNext(int howMany)
         {
             _start += _count;
             _count = howMany;
             return BuilderProxy;
         }
 
-        public TBuilder ThePrevious(int howMany)
+        /// <summary>
+        /// Will target the last x objects (as specified) for subsequent builder calls (or .With call).
+        /// You can combine this with .ThePrevious(y) to target the previous y after the last x.
+        /// </summary>
+        /// <param name="howMany">The last {howMany} objects should be targeted?</param>
+        /// <returns>The builder proxy so that calls can continue to be chained</returns>
+        public TBuilder TheLast(int howMany)
         {
-            _start -= howMany;
+            _start = _list.Count - howMany;
             _count = howMany;
             return BuilderProxy;
         }
 
-        public TBuilder TheLast(int howMany)
+        /// <summary>
+        /// Will target the previous x objects (as specified) for subsequent builder calls (or .With call).
+        /// </summary>
+        /// <param name="howMany">The previous {howMany} objects should be targeted?</param>
+        /// <returns>The builder proxy so that calls can continue to be chained</returns>
+        public TBuilder ThePrevious(int howMany)
         {
-            _start = _list.Count - howMany;
+            _start -= howMany;
             _count = howMany;
             return BuilderProxy;
         }
 
+        /// <summary>
+        /// Will target all objects for subsequent builder calls (or .With call).
+        /// </summary>
+        /// <returns>The builder proxy so that calls can continue to be chained</returns>
         public TBuilder All()
         {
             _start = 0;
             _count = _list.Count;
             return BuilderProxy;
         }
 
+        /// <summary>
+        /// Will apply the given lambda expression to all builders that are currently targeted (e.g. via .TheFirst, .TheNext, etc. calls).
+        /// </summary>
+        /// <param name="modifier">The lambda expression to apply to the targeted builders</param>
+        /// <returns>The builder proxy so that calls can continue to be chained</returns>
         public ListBuilder<TObject, TBuilder> With(Func<TBuilder, TBuilder> modifier)
         {
             _list.Skip(_start)
@@ -155,6 +105,10 @@ public ListBuilder<TObject, TBuilder> With(Func<TBuilder, TBuilder> modifier)
             return this;
         }
 
+        /// <summary>
+        /// Builds the list of objects by processing all of the builder calls and then calling .Build on all the builders.
+        /// </summary>
+        /// <returns>The list of generated objects</returns>
         public IList<TObject> BuildList()
         {
             return _list.Select(b => b.Build()).ToArray();
@@ -168,23 +122,4 @@ internal void Execute(IInvocation invocation)
                 .ForEach(b => invocation.Method.Invoke(b, invocation.Arguments));
         }
     }
-
-    public class EnsureAllMethodsVirtual : IProxyGenerationHook
-    {
-        public void MethodsInspected()
-        {
-        }
-
-        public void NonProxyableMemberNotification(Type type, MemberInfo memberInfo)
-        {
-            if (new[]{"get_Any", "Build", "AsProxy", "Get", "GetOrDefault", "Set", "Has", "get_ListBuilder", "set_ListBuilder"}.Contains(memberInfo.Name))
-                return;
-            throw new InvalidOperationException(string.Format("Tried to build a list with a builder who has non-virtual method. Please make {0} on type {1} virtual.", memberInfo.Name, type.Name));
-        }
-
-        public bool ShouldInterceptMethod(Type type, MethodInfo methodInfo)
-        {
-            return true;
-        }
-    }
 }