workbench 0.1

data/Gemfile

@@ -0,0 +1,2 @@
+source :rubygems
+gemspec

data/MIT_LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 LeadTune
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,119 @@
+= About
+
+Workbench is tiny, lean, mean, intuitive factory system that exploits
+some lesser known features of ruby to deliver a robust, easy to
+understand solution without the tangled mess of meta-magic.
+
+(disclaimer: some meta-magic involved, but it is minimal)
+
+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).
+* 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.
+
+= Requirements
+
+Builder works with Ruby 1.8.7 and above.
+
+= Why?
+
+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.
+
+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.
+
+= Usage
+
+Workbench is very simple to use, but does require a small amount of
+knowledge for othings to be immediately clear. Grok the following:
+
+Add to your Gemspec:
+
+  gem "workbench"
+
+Create a module in any place of your choosing:
+
+<code>spec/support/workbench_builders.rb</code>
+
+  module WorkbenchBuilders
+    extend Workbench
+
+    ... your code here. See sample below ...
+  end
+
+Now, include the module anywhere you want (yes, you can even include
+it in your ERB views, you sick freak). Most will probably want to
+include it in their global test config or RSpec config (like so):
+
+  RSpec.configure do |config|
+    include WorkbenchBuilders
+    ...
+  end
+
+= Sample Builders
+
+  module WorkbenchBuilders
+    # 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).
+    #
+    # The following methods will be automatically added in this module:
+    #
+    # * new_user(attributes)
+    # * create_user(attributes)
+    # * find_or_create_user(attributes)
+    #
+    # user_defaults will be called with a new instance of User. Any
+    # 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
+      u.role ||= "user"
+    end
+
+    # An admin user. Since we intend to build a User and not an
+    # AdminUser (the would-be inferred class name), we need to declare
+    # the class name just before the builder method definition.
+    #
+    # The following methods will be automatically added in this module:
+    #
+    # * new_admin_user(attributes)
+    # * 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.
+
+    class_name :User
+    def admin_user_defaults(u)
+      u.role ||= "admin"
+      user_defaults(u)
+    end
+  end
+
+See:
+
+* Workbench
+* Workbench#sequence

data/lib/workbench.rb

@@ -0,0 +1,66 @@
+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
+
+  # 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
+  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
+    end
+    super
+  end
+
+  def define_builder_methods(name, 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)
+      end
+    end
+
+    define_method("create_#{name}") do |*args|
+      send("new_#{name}", *args).tap do |model|
+        if model.respond_to?(:save!) # save should raise if unsuccessful
+          model.save!
+        else
+          model.save
+        end
+      end
+    end
+
+    define_method("find_or_create_#{name}") do |*args|
+      attrs = args[0] || { }
+      klass.where(attrs).first || send("create_#{name}", attrs)
+    end
+  end
+
+  def inferred_builder_class_name(name)
+    if name.to_s.match(/^(.+)_defaults$/)
+      $1.to_sym
+    end
+  end
+
+end

data/lib/workbench/string_helpers.rb

@@ -0,0 +1,16 @@
+module Workbench
+  # A collection of needed String methods. They are here to remove a dependency on ActiveSupport. You can use them if you want... but you probably should use ActiveSupport or copy them into your project.
+  module StringHelpers
+    # takes :User, "user", or :user and returns User
+    def self.constantize(value)
+      value = value.to_s
+      value = classify(value) unless value =~ /^[A-Z]/
+      eval(value.to_s)
+    end
+
+    # "transforms 'namespace/model_name' to 'Namespace::ModelName'"
+    def self.classify(string)
+      string.to_s.gsub("/", "::").gsub(/(_|\b)(.)/) { |r| r[-1..-1].upcase }
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,17 @@
+require 'rspec'
+require File.expand_path("./lib/workbench.rb")
+
+class User
+  attr_accessor :name, :phone
+
+  def save
+    @saved = true
+  end
+
+  def new_record?
+    ! @saved
+  end
+end
+
+Rspec.configure do
+end

data/spec/workbench/string_helpers_spec.rb

@@ -0,0 +1,11 @@
+require 'spec_helper'
+
+module Workbench
+  describe StringHelpers do
+    describe "#classify" do
+      it "transforms 'namespace/model_name' to 'Namespace::ModelName'" do
+        StringHelpers.classify('namespace/model_name').should == 'Namespace::ModelName'
+      end
+    end
+  end
+end

data/spec/workbench_spec.rb

@@ -0,0 +1,126 @@
+require 'spec_helper'
+
+describe Workbench do
+  USER_BUILDER = Module.new do
+    extend Workbench
+
+    def user_defaults(u)
+      u.name  ||= "Bill"
+      u.phone ||= "999-999-9999"
+    end
+  end
+
+  describe "defining" do
+    it "creates a module with create_, new_, and find_or_create_" do
+      builder_methods = Module.new do
+        extend Workbench
+
+        def user_defaults(u)
+          u.name ||= "Bill"
+          u.phone ||= "999-999-9999"
+        end
+      end
+
+      methods = builder_methods.instance_methods.map(&:to_sym)
+      methods.should include(:new_user)
+      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
+      builder_methods = Module.new do
+        extend Workbench
+
+        class_name :User
+        def admin_user_defaults(u)
+          u.name = "Bill"
+          u.phone = "999-999-9999"
+        end
+      end
+
+      extend builder_methods
+      new_admin_user.class.should == User
+    end
+
+  end
+
+  describe ".sequence" do
+    it "defines a sequence which, when used, yields an incrementing number and returns the value from the block" do
+      builder_methods = Module.new do
+        extend Workbench
+
+        sequence(:name) { |n| "Name #{n}" }
+      end
+
+      extend builder_methods
+      next_name.should == "Name 1"
+      next_name.should == "Name 2"
+    end
+
+    it "can define a sequence that starts with any value that responds to #succ" do
+      builder_methods = Module.new do
+        extend Workbench
+
+        sequence(:code, "A") { |n| "ABC-#{n}" }
+      end
+
+      extend builder_methods
+      next_code.should == "ABC-A"
+      next_code.should == "ABC-B"
+    end
+
+    it "defines sequences without a proc" do
+      builder_methods = Module.new do
+        extend Workbench
+
+        sequence(:code, "AAA")
+      end
+
+      extend builder_methods
+      next_code.should == "AAA"
+      next_code.should == "AAB"
+    end
+
+  end
+
+  describe "#new_(builder_name)" do
+    before(:each) do
+      extend USER_BUILDER
+    end
+
+    it "initializes a model with .new, calls user_defaults, but doesn't call save" do
+      user = new_user
+      user.name.should  == "Bill"
+      user.phone.should == "999-999-9999"
+      user.should be_a_new_record
+    end
+
+    it 'sets attributes passed as an argument by calling Model#attribute=' do
+      user = new_user(:name => "Bob")
+      user.name.should == "Bob"
+      user.phone.should == "999-999-9999"
+    end
+  end
+
+  describe "#create_(builder_name)" do
+    it "behaves like #new_(builder_name), but calls save at the end" do
+      extend USER_BUILDER
+      user = create_user(:name => "Bob")
+      user.name.should == "Bob"
+      user.phone.should == "999-999-9999"
+      user.should_not be_a_new_record
+      user.name.should == "Bob"
+    end
+  end
+
+  describe "#find_of_create_(builder_name)" do
+    it "calls Model.where(attributes).first. If a model is returned, use that, otherwise, create it" do
+      extend USER_BUILDER
+      bob_user = create_user(:name => "Bob")
+      User.should_receive(:where).with({ :name => "Bob" }).and_return([bob_user])
+      find_or_create_user(:name => "Bob").should == bob_user
+    end
+  end
+end

metadata

@@ -0,0 +1,100 @@
+--- !ruby/object:Gem::Specification 
+name: workbench
+version: !ruby/object:Gem::Version 
+  prerelease: 
+  version: "0.1"
+platform: ruby
+authors: 
+- Tim Harper
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-08-11 00:00:00 -06:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: "2.6"
+  type: :development
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: ruby-debug19
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :development
+  version_requirements: *id002
+description: |
+  There are a lot of factory frameworks, why one more? In my experience
+  the otherones use fancy DSLs that were intended to increase
+  readability but instead increased confusion.
+  
+  Workbench doesn't use a fancy DSL. It uses ruby. It doesn't use any
+  fancy tricks like providing proxy objects for modification, workbench
+  builders operate on the actual model. Since it uses very little
+  tricks, it is also ORM agnostic. If your models respond to '.new' and
+  you set attributes by calling #attribute=, then Workbench will work
+  with your model.
+  
+  I have a hard time understanding why all the complexity around factory
+  builders has grown, but often I look at the resulting DSL and say
+  "That's more work than just defining a method and calling Model.new!"
+
+email: 
+- tim@leadtune.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- spec/spec_helper.rb
+- spec/workbench/string_helpers_spec.rb
+- spec/workbench_spec.rb
+- lib/workbench/string_helpers.rb
+- lib/workbench.rb
+- MIT_LICENSE
+- README.rdoc
+- Gemfile
+has_rdoc: true
+homepage: http://github.com/leadtune/workbench
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: 1.3.6
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.6.2
+signing_key: 
+specification_version: 3
+summary: A small, simple ORM agnostic factory library that does the job without any crazy tricks.
+test_files: []
+