workbench 0.1 → 0.2

data/README.rdoc

@@ -8,35 +8,32 @@ understand solution without the tangled mess of meta-magic.
 
 Highlights:
 
-* Does not use method_missing, Module.included, Module.extended magic.
-  Builder modules, in the end, contain no magic (some meta-programming
-  used to generate modules, but it ends there).
+* Does not use method_missing. Builder modules, in the end, contain no
+  magic (meta-programming only used to generate modules).
 * No DSL. Builders are defined by declaring ruby methods (can your
   editor jump DSL declarations in a file?). Easily call other builder
   methods to achieve inheritance (see example below) or whatever you
   please.
-* Operate on actual instances of the objects. An abstraction layer is
-  unnecessary. If your Object supports it, you can do it. Wield ruby.
-* No dependencies (not even ActiveSupport). If your Object defines
-  .new (with no params), #save, and #valid? then Workbench can use it.
-  If your Object implements #save! as method to raise if model not
-  valid, it uses it.
+* Operate on actual instances of the objects. Wield ruby.
+* No dependencies (not even ActiveSupport).
+* Works with any Object that defines .new (with no params) and #save.
+  Will use #valid? and #save! if the methods exist.
 
 = Requirements
 
 Builder works with Ruby 1.8.7 and above.
 
-= Why?
+= Why another factory system?
 
-There are a lot of factory frameworks, why one more? In my experience
-the other ones use fancy DSLs that were intended to increase
-readability but instead increased confusion and get in the way.
+There are a lot of factory frameworks, why one more? I felt I had an
+idea to maximize simplicity and minimize the experience of the factory
+system getting in the way by following a few conventions that should
+cover most use cases, while keeping it robust by getting out of the
+way.
 
-Then the code base. Some have hundreds of lines (for a framework to
-help you create instances of your objects? Really?). Workbench is less
-than 70 lines, and every line counts. Moderately experienced rubyists
-should have no trouble understanding the code, and there is not that
-much to parse.
+Workbench is less than 70 lines, and every line counts. Moderately
+experienced rubyists should have no trouble understanding the code,
+and there is not that much to parse.
 
 = Usage
 
@@ -72,11 +69,12 @@ include it in their global test config or RSpec config (like so):
     # Activate Workbench for this module. MUST go at the top.
     extend Workbench
 
-    # Will define #next_name and #next_code. See Workbench#sequence rdoc for more info.
-    sequence(:name) { |n| "Name #{n}" }
-    sequence(:code, "AAA")
-
-    # Declare builder for model User (class name is infered by the method name).
+    # Declare builder for model User (class name is infered by the
+    # method name).
+    #
+    # A builder method may receive between 1 and 3 arguments. (due to
+    # shortcoming in ruby 1.8.7, if you specify any optional
+    # arguments, Workbench will assume it can send all 3 arguments).
     #
     # The following methods will be automatically added in this module:
     #
@@ -88,9 +86,9 @@ include it in their global test config or RSpec config (like so):
     # attributes provided to new_user et al will be sent to the User
     # instance via user#send("#{attribute_name}=", value)
 
-    def user_defaults(u)
-      u.name ||= next_name
-      u.code ||= next_code
+    def user_defaults(u, n)
+      u.name ||= "Name #{n}"
+      u.code ||= "U#{n}"
       u.role ||= "user"
     end
 
@@ -104,12 +102,14 @@ include it in their global test config or RSpec config (like so):
     # * create_admin_user(attributes)
     # * find_or_create_admin_user(attributes)
     #
-    # Caveat: find_or_create_admin_user is not aware of the role, so it will return a non-admin user just the same that matches the attributes you provide.
+    # Caveat: find_or_create_admin_user is not aware of the role, so
+    # it will return a non-admin user just the same that matches the
+    # attributes you provide.
 
-    class_name :User
-    def admin_user_defaults(u)
+    use_class :User
+    def admin_user_defaults(u, n)
       u.role ||= "admin"
-      user_defaults(u)
+      user_defaults(u, n)
     end
   end
 
@@ -117,3 +117,103 @@ See:
 
 * Workbench
 * Workbench#sequence
+
+= Counters
+
+Counters are scoped to the class name. In the following example, user
+and admin_user will count together:
+
+    module Builders
+      extend Workbench
+      def user_defaults(u, n)
+        ...
+      end
+
+      use_class :User
+      def admin_user_defaults(u, n)
+        ...
+      end
+    end
+
+    new_admin_user # n = 1
+    new_user       # n = 2
+    new_admin_user # n = 3
+
+In cases where have two builders that use different classes but the
+same table and require them to count together, use #count_with:
+
+    module Builders
+      extend Workbench
+
+      count_with :Publication
+      def book_defaults(u, n)
+        ...
+      end
+
+      count_with :Publication
+      def article_defaults(u, n)
+        ...
+      end
+    end
+
+    new_book        # n = 1
+    new_publication # n = 2
+    new_book        # n = 3
+
+== Resetting counters
+
+If you do clear your database for every test, run the following before
+or after each test is run. (a la config.before(:each)...)
+
+  Workbench.reset_counters!
+
+Otherwise you may have tests that fail due to an increment getting so
+big that it breaks a length validation, or something of the sort. A
+failure that would probably not fail if the test were run
+individually.
+
+= A note about false / nil
+
+Workbench builders contain a lot of conditionals, testing for nil or
+false to see if a value is populated. This is problematic, naturally,
+if you need to provide nil or false as an override value.
+
+IE:
+
+    def user_defaults(u)
+      u.name ||= "Bob"
+    end
+
+    new_user(:name => nil)
+
+Workbench is opinionated as follows:
+
+* Only set the bare minimum: If a model accepts false or nil as a
+  valid value, you should consider leaving it false or nil by the
+  builder.
+
+* When designing data models, Nil / False should represent the
+  neutral, non-exceptional case: IE: prefer User#has_admin_priviledges
+  over User#deny_admin_privileges.
+
+* You should never provide attributes to new_<model> or create_<model>
+  that produce an invalid object. When testing validation, instantiate
+  a valid instance with new_<model> and then modify it outside of the
+  builder as follows:
+
+    context "validation"
+      it "requires a name field" do
+        u = new_user
+        u.name = nil
+        u.should have(1).errors_on(:name)
+      end
+    end
+
+These conventions should work for 99% of scenarios. In the case you
+find a good reason to override an attribute with nil or false, defined
+your builder method to receive 3 arguments to receive the overrides
+hash:
+
+    def user_defaults(u, n, overrides = {})
+      u.name = "Bob" unless overrides.has_key?(:name)
+    end

data/lib/workbench.rb

@@ -1,43 +1,72 @@
 require File.expand_path('../workbench/string_helpers', __FILE__)
 module Workbench
-
-  # Defines a sequence method named next_#{name}.
-  #
-  # [value] - Optional. An incrementable value (any object that responds to #succ, Fixnum, Time, String, Symbol, etc.)
-  # [block] - Optional. A formatter block. Successive values with be passed to block, and sequence method will return result of block.
-  def sequence(name, value = 1, &block)
-    define_method("next_#{name}") do
-      (block ? block.call(value) : value).tap do
-        value = value.succ
-      end
-    end
-  end
+  COUNTERS = Hash.new(0)
 
   # Declare that the next builder method is to use the said class
   # (Symbol such as :User or string such as "Models::User" are
   # acceptable)
-  def class_name(name)
-    @next_class_name = name
+  def use_class(name)
+    @next_class = name
+  end
+
+  # Declare that the next builder method is to count scoped to the following class,
+  #
+  # module Builders
+  #   extend Workbench
+  #
+  #   def book_defaults(u, n)
+  #     ...
+  #   end
+  #
+  #   count_with :Book
+  #   def article_defaults(u, n)
+  #     ...
+  #   end
+  # end
+  #
+  # new_book        # n = 1
+  # new_publication # n = 2
+  # new_book        # n = 3
+  #
+  # expects a Symbol such as :User or string such as "Models::User" that maps to a valid class name.
+  def count_with(name)
+    @next_count_with = name
+  end
+
+  # The counter routine. Provide a key, get back an incrementer.
+  def self.counter(key)
+    COUNTERS[key] += 1
+  end
+
+  # Reset all counters. It doesn't happen automatically, you'll likley
+  # want to call this method before or after each test is run
+  def self.reset_counters!
+    COUNTERS.clear
   end
 
 private
   def method_added(name)
     if builder_name = inferred_builder_class_name(name)
-      klass = StringHelpers.constantize(@next_class_name || builder_name)
-      define_builder_methods(builder_name, klass)
-      @next_class_name = nil
+      klass         = StringHelpers.constantize(@next_class || builder_name)
+      counter_klass = StringHelpers.constantize(@next_count_with || klass)
+      define_builder_methods(builder_name, klass, counter_klass)
+      @next_class, @next_count_with = nil
     end
     super
   end
 
-  def define_builder_methods(name, klass)
+  def define_builder_methods(name, klass, counter_klass)
     define_method("new_#{name}") do |*args|
       attributes = args[0] || { }
       klass.new.tap do |model|
         attributes.each do |k, v|
           model.send("#{k}=", v)
         end
-        send("#{name}_defaults", model)
+        build_method = method("#{name}_defaults")
+        p = [model]
+        p << Workbench.counter(counter_klass) if build_method.arity >= 2 || build_method.arity <= -1
+        p << attributes                       if build_method.arity >= 3 || build_method.arity <= -1
+        build_method.call *p
       end
     end
 

data/lib/workbench/string_helpers.rb

@@ -3,8 +3,10 @@ module Workbench
   module StringHelpers
     # takes :User, "user", or :user and returns User
     def self.constantize(value)
+      return value if value.is_a?(Module)
       value = value.to_s
       value = classify(value) unless value =~ /^[A-Z]/
+      value = "::#{value}" unless value =~ /^:/
       eval(value.to_s)
     end
 

data/spec/spec_helper.rb

@@ -2,7 +2,7 @@ require 'rspec'
 require File.expand_path("./lib/workbench.rb")
 
 class User
-  attr_accessor :name, :phone
+  attr_accessor :name, :phone, :active
 
   def save
     @saved = true
@@ -11,6 +11,8 @@ class User
   def new_record?
     ! @saved
   end
+
+  alias active? active
 end
 
 Rspec.configure do

data/spec/workbench/string_helpers_spec.rb

@@ -2,6 +2,30 @@ require 'spec_helper'
 
 module Workbench
   describe StringHelpers do
+    describe "#constantize" do
+      it "returns a constant several levels deep, beginning from object" do
+        StringHelpers.constantize("::Workbench::StringHelpers").should == Workbench::StringHelpers
+      end
+
+      it "defaults to root if no preceeding colon is provided" do
+        lambda {
+          StringHelpers.constantize("StringHelpers")
+        }.should raise_error(NameError, /uninitialized constant StringHelpers/)
+      end
+
+      it "automatically 'classifies' underscored class names" do
+        StringHelpers.constantize("workbench/string_helpers").should == Workbench::StringHelpers
+      end
+
+      it "returns the provided modules" do
+        StringHelpers.constantize(Workbench).should == Workbench
+      end
+
+      it "returns the provided classes " do
+        StringHelpers.constantize(Class).should == Class
+      end
+    end
+
     describe "#classify" do
       it "transforms 'namespace/model_name' to 'Namespace::ModelName'" do
         StringHelpers.classify('namespace/model_name').should == 'Namespace::ModelName'

data/spec/workbench_spec.rb

@@ -10,7 +10,11 @@ describe Workbench do
     end
   end
 
-  describe "defining" do
+  before(:each) do
+    Workbench.reset_counters!
+  end
+
+  describe "defining builders" do
     it "creates a module with create_, new_, and find_or_create_" do
       builder_methods = Module.new do
         extend Workbench
@@ -26,61 +30,111 @@ describe Workbench do
       methods.should include(:create_user)
       methods.should include(:find_or_create_user)
     end
-  end
 
-  describe ".class_name" do
-    it "over-rides the class to use for the next defined builder" do
+    it "passes the next counter value to the builder method when arity = 2" do
       builder_methods = Module.new do
         extend Workbench
 
-        class_name :User
-        def admin_user_defaults(u)
-          u.name = "Bill"
-          u.phone = "999-999-9999"
+        def user_defaults(u, n)
+          u.name ||= "Bill #{n}"
         end
       end
 
       extend builder_methods
-      new_admin_user.class.should == User
+
+      new_user.name.should == "Bill 1"
+      new_user.name.should == "Bill 2"
     end
 
-  end
+    it "passes the overrides hash when arity = 3" do
+      builder_methods = Module.new do
+        extend Workbench
+
+        def user_defaults(u, n, overrides)
+          u.active = true unless overrides.has_key?(:active)
+        end
+      end
+
+      extend builder_methods
+      new_user(:active => false).should_not be_active
+    end
 
-  describe ".sequence" do
-    it "defines a sequence which, when used, yields an incrementing number and returns the value from the block" do
+    it "passes the overrides hash if arity is < -1 (unfortunately, the value when a splat or default value used)" do
       builder_methods = Module.new do
         extend Workbench
 
-        sequence(:name) { |n| "Name #{n}" }
+        def user_defaults(u, n = -1, overrides = { })
+          u.active = true unless overrides.has_key?(:active)
+        end
       end
 
       extend builder_methods
-      next_name.should == "Name 1"
-      next_name.should == "Name 2"
+      new_user(:active => false).should_not be_active
     end
+  end
 
-    it "can define a sequence that starts with any value that responds to #succ" do
+  describe "counting" do
+    it "scopes counting to builders with the same class" do
       builder_methods = Module.new do
         extend Workbench
 
-        sequence(:code, "A") { |n| "ABC-#{n}" }
+        def user_defaults(u, n)
+          u.name ||= "User #{n}"
+        end
+
+        use_class :user
+        def admin_user_defaults(u, n)
+          u.name ||= "Admin #{n}"
+          user_defaults(u, n)
+        end
       end
 
       extend builder_methods
-      next_code.should == "ABC-A"
-      next_code.should == "ABC-B"
+      new_user       .name.should == "User 1"
+      new_admin_user .name.should == "Admin 2"
+      new_user       .name.should == "User 3"
     end
 
-    it "defines sequences without a proc" do
+  end
+
+  describe ".count_with" do
+    it "causes the counter to count with the provided model" do
+      admin_user = Class.new(User)
       builder_methods = Module.new do
         extend Workbench
 
-        sequence(:code, "AAA")
+        def user_defaults(u, n)
+          u.name ||= "User #{n}"
+        end
+
+        use_class admin_user
+        count_with :user
+        def admin_user_defaults(u, n)
+          u.name ||= "Admin #{n}"
+          user_defaults(u, n)
+        end
+      end
+      extend builder_methods
+      new_user       .name.should == "User 1"
+      new_admin_user .name.should == "Admin 2"
+      new_user       .name.should == "User 3"
+    end
+  end
+
+  describe ".use_class" do
+    it "over-rides the class to use for the next defined builder" do
+      builder_methods = Module.new do
+        extend Workbench
+
+        use_class :User
+        def admin_user_defaults(u)
+          u.name = "Bill"
+          u.phone = "999-999-9999"
+        end
       end
 
       extend builder_methods
-      next_code.should == "AAA"
-      next_code.should == "AAB"
+      new_admin_user.class.should == User
     end
 
   end

metadata

@@ -2,15 +2,17 @@
 name: workbench
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: "0.1"
+  version: "0.2"
 platform: ruby
 authors: 
 - Tim Harper
+- Eric Wollesen
+- Ben Mabey
 autorequire: 
 bindir: bin
 cert_chain: []
 
-date: 2011-08-11 00:00:00 -06:00
+date: 2011-08-19 00:00:00 -06:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency