hero 0.0.3 → 0.0.4

data/README.md

@@ -1,12 +1,14 @@
 # Hero
 
+![Hero GEM](http://hopsoft.github.com/hero/images/hero.jpg) 
+
 ## Its a bird, its a plane, its... its... my Hero
 
-![Hero GEM](http://hopsoft.github.com/hero/images/hero.jpg) 
+---
 
-Ever wish that you could unwind the spaghetti and get out of the corner you've been backed into?
+*Controlling complexity is the essence of computer programming. -- [Brian Kernighan](http://en.wikipedia.org/wiki/Brian_Kernighan)*
 
-### Hero is here to save the day
+---
 
 I've seen my share of poor app structure. 
 Hell, I wrote most of it.
@@ -17,161 +19,25 @@ The question remains. **Where do I put my business logic?**
 Finally... an answer that might even make DHH proud. 
 One that evolved from the real world with concrete use cases and actual production code.
 
-## Process Modeling
+## Why Hero?
 
-The problem has always been: How to effectively model a business process within your app.
+* App structure matches the mental map of your business
+* Testable coponents
+* Faster ramp up time for new team members
+* Easily handles changing requirements 
+
+### Process Modeling
+
+The problem has always been: **How do you effectively model a business process within your app?**
 
 Things start simply enough but eventually edge cases force *gotchas* into
 various libs, modules, and classes. Before you know you it,
 you have a lump of spaghetti that's difficult to maintain and even harder to improve.
 
-### Enter Hero
-
 Hero provides a simple pattern that encourages you to 
 <a href="http://en.wikipedia.org/wiki/Decomposition_(computer_science)">decompose</a>
-business processes into managable chunks.
-
-And... the best part is, they are easily tested.
+these processes into managable chunks. And the best part... the components can be easily tested.
 
 ---
 
-Here's an example. 
-Assume we have a Rails app that needs to support logins. 
-
-Our implementation might look something like this.
-
-```ruby
-# app/controllers/logins_controller.rb
-class LoginsController < ApplicationController
-
-  def create
-    if user = User.authenticate(params[:username], params[:password])
-      session[:current_user_id] = user.id
-      redirect_to root_url
-    end
-  end
-
-  def destroy
-    @_current_user = session[:current_user_id] = nil
-    redirect_to root_url
-  end
-
-end
-```
-
-```ruby
-# app/controllers/application_controller.rb
-class ApplicationController < ActionController::Base
-  before_filter :require_login
- 
-  private
- 
-  def require_login
-    unless logged_in?
-      flash[:error] = "You must be logged in to access this section"
-      redirect_to new_login_url # halts request cycle
-    end
-  end
- 
-  def logged_in?
-    !!current_user
-  end
-
-  def current_user
-    @_current_user ||= session[:current_user_id] &&
-      User.find_by_id(session[:current_user_id])
-  end
-
-end
-```
-
-Hero approaches this problem differently. 
-It asks us to <a href="http://en.wikipedia.org/wiki/Decomposition_(computer_science)">decompose</a>
-the login requirement into a business processes looks something like this.
-
-#### Login
-
-1. Authenticate the user
-1. Save user info to session
-1. Send user to home page
-
-#### Logout
-
-1. Remove user session
-1. Send user to home page
-
-#### Protect Page
-
-1. Verify the user is logged in
-
-Note that we just defined an [ontology](http://en.wikipedia.org/wiki/Process_ontology) 
-that can be used to discuss the requirement and its implementation with non developers.
-
-Here's an example of an implementation with Hero.
-
-```ruby
-# lib/errors.rb
-class AuthenticationError < StandardError; end
-class AuthorizationError < StandardError; end
-```
-
-```ruby
-# config/initializers/login.rb
-Hero::Formula[:login].add_step do |context|
-  user = User.authenticate(context.params[:username], context.params[:password])
-  raise AuthenticationError unless user
-  context.session[:current_user_id] = user.id
-end
-
-Hero::Formula[:logout].add_step do |context|
-  context.session[:current_user_id] = nil
-end
-
-Hero::Formula[:protect_page].add_step do |context|
-  raise AuthorizationError if context.session[:current_user_id].nil?
-end
-```
-
-```ruby
-# app/controllers/logins_controller.rb
-class LoginsController < ApplicationController
-  rescue_from AuthenticationError { render "new" }
-
-  def create
-    Hero::Formula[:login].run(self)
-    redirect_to root_url
-  end
-
-  def destroy
-    Hero::Formula[:logout].run(self)
-    redirect_to root_url
-  end
-
-end
-```
-
-```ruby
-# app/controllers/application_controller.rb
-class ApplicationController < ActionController::Base
-  before_filter :protect
-  rescue_from AuthorizationError, :with => :force_login
-
-  private
-
-  def protect
-    Hero::Formula[:protect_page].run(self)
-  end
-
-  def force_login
-    flash[:error] = "You must be logged in to access this section"
-    redirect_to new_login_url
-  end
- 
-end
-```
-
-I know what you're thinking, and you're right. 
-This doesn't pass DHH's before/after test, 
-but lets start throwing edge cases at it and see what happens.
-
 More soon. Stay tuned...

data/lib/hero.rb

@@ -1,3 +1,9 @@
 Dir[File.join(File.dirname(__FILE__), "hero", "*rb")].each do |file|
   require file
 end
+
+module Hero
+  class << self
+    attr_accessor :logger
+  end
+end

data/lib/hero/formula.rb

@@ -1,17 +1,26 @@
 require 'observer'
 require 'singleton'
 require 'forwardable'
+require File.join(File.dirname(__FILE__), "observer")
 
 module Hero
+
   class Formula
-    include Observable
-    include Singleton
 
+    # Class attributes & methods ==============================================
     class << self
       extend Forwardable
       def_delegator :formulas, :each, :each
       def_delegator :formulas, :length, :count
 
+      def publish
+        value = []
+        each do |name, formula|
+          value << formula.publish
+        end
+        value.join("\n\n")
+      end
+
       def reset
         formulas.values.each { |f| f.delete_observers }
         @formulas = {}
@@ -22,10 +31,13 @@ module Hero
       end
 
       def register(name)
-        observer = Hero::Observer.new
+        observer = Hero::Observer.new(name)
         formula = Class.new(Hero::Formula).instance
         formula.add_observer(observer)
-        formula.instance_eval { @observer = observer }
+        formula.instance_eval do
+          @name = name
+          @observer = observer
+        end
         formulas[name] = formula
       end
 
@@ -36,9 +48,21 @@ module Hero
       end
     end
 
-    def add_step(step=nil, &block)
-      step ||= block if block_given?
-      @observer.steps << step
+    # Instance attributes & methods ===========================================
+    extend Forwardable
+    include Observable
+    include Singleton
+
+    attr_reader :name, :observer
+    def_delegator :observer, :steps, :steps
+    def_delegator :observer, :add_step, :add_step
+
+    def publish
+      value = [name]
+      steps.each_with_index do |step, index|
+        value << "#{(index + 1).to_s.rjust(3)}. #{step.keys.first}"
+      end
+      value.join("\n")
     end
 
     def notify(context=nil, options={})

data/lib/hero/observer.rb

@@ -1,13 +1,31 @@
 module Hero
   class Observer
+    attr_reader :formula_name
+
+    def initialize(formula_name)
+      @formula_name = formula_name
+    end
 
     def steps
-      @steps ||= []
+      @steps ||= {}
+      @steps.sort{ |a, b| a.last[:index] <=> b.last[:index] }.map{ |k, v| { k => v[:step] } }
+    end
+
+    def add_step(name, step=nil, &block)
+      @steps ||= {}
+      step ||= block if block_given?
+      @steps[name] = { :step => step, :index => @steps.length }
     end
 
     def update(context, options={})
-      steps.each { |step| step.call(context, options) }
+      steps.each do |step|
+        if Hero.logger
+          Hero.logger.info "HERO Formula: #{formula_name}, Step: #{step.keys.first}, Context: #{context.inspect}, Options: #{options.inspect}"
+        end
+        step.values.first.call(context, options)
+      end
     end
 
   end
 end
+

data/spec/formula_spec.rb

@@ -0,0 +1,138 @@
+require "spec_helper"
+
+describe Hero::Formula do
+  include GrumpyOldMan
+
+  before :each do
+    Hero.logger = nil
+    Hero::Formula.reset
+  end
+
+  it "should support reset" do
+    Hero::Formula.register(:test_formula)
+    assert_equal Hero::Formula.count, 1
+    Hero::Formula.reset
+    assert_equal Hero::Formula.count, 0
+  end
+
+  it "should support registering a formula" do
+    Hero::Formula.register(:test_formula)
+    assert_equal Hero::Formula.count, 1
+    assert Hero::Formula[:test_formula].is_a? Hero::Formula
+  end
+
+  it "should auto register formulas" do
+    Hero::Formula[:test_formula]
+    assert_equal Hero::Formula.count, 1
+    assert Hero::Formula[:test_formula].is_a? Hero::Formula
+  end
+
+  it "should support registering N number of formulas" do
+    10.times { |i| Hero::Formula.register("example_#{i}") }
+    assert_equal Hero::Formula.count, 10
+  end
+
+  it "should unregister formula observers on reset" do
+    formula = Hero::Formula[:test_formula]
+    assert_equal Hero::Formula.count, 1
+    formula.add_step(:one) {}
+    assert_equal formula.count_observers, 1
+    Hero::Formula.reset
+    assert_equal Hero::Formula.count, 0
+    assert_equal formula.count_observers, 0
+  end
+
+  it "should publish all formulas" do
+    Hero::Formula[:first].add_step(:one) {}
+    Hero::Formula[:first].add_step(:two) {}
+    Hero::Formula[:first].add_step(:three) {}
+    Hero::Formula[:first].add_step(:four) {}
+
+    Hero::Formula[:second].add_step(:one) {}
+    Hero::Formula[:second].add_step(:two) {}
+    Hero::Formula[:second].add_step(:three) {}
+    Hero::Formula[:second].add_step(:four) {}
+
+    expected = "first  1. one  2. two  3. three  4. foursecond  1. one  2. two  3. three  4. four"
+    assert_equal Hero::Formula.publish.gsub(/\n/, ""), expected
+  end
+
+  describe "a registered formula" do
+    it "should support adding steps" do
+      Hero::Formula[:test_formula].add_step(:one) { }
+      assert_equal Hero::Formula.count, 1
+      assert_equal Hero::Formula[:test_formula].steps.length, 1
+    end
+
+    def invoke_notify_method(name)
+      step_ran = false
+      target = Object.new
+      Hero::Formula[:test_formula].add_step(:one) do |t, opts|
+        assert_equal t, target
+        assert_equal opts[:foo], :bar
+        step_ran = true
+      end
+      Hero::Formula[:test_formula].notify(target, :foo => :bar)
+      assert step_ran
+    end
+
+    it "should support notify" do
+      invoke_notify_method(:notify)
+    end
+
+    it "should support run" do
+      invoke_notify_method(:run)
+    end
+
+    it "should support running step defined in a class" do
+      class Step
+        def call(context, options)
+          options[:context] = context
+        end
+      end
+
+      opts = {}
+      Hero::Formula[:test_formula].add_step(:one, Step.new)
+      Hero::Formula[:test_formula].run(:foo, opts)
+      assert_equal opts[:context], :foo
+    end
+
+    it "should support running multiple tests" do
+      log = {}
+      Hero::Formula[:test_formula].add_step(:one) { |o, l| l[:one] = true }
+      Hero::Formula[:test_formula].add_step(:two) { |o, l| l[:two] = true }
+      Hero::Formula[:test_formula].run(self, log)
+      assert log[:one]
+      assert log[:two]
+    end
+
+    it "should publish all steps in the formula" do
+      Hero::Formula[:test_formula].add_step(:one) {}
+      Hero::Formula[:test_formula].add_step(:two) {}
+      Hero::Formula[:test_formula].add_step(:three) {}
+      Hero::Formula[:test_formula].add_step(:four) {}
+      expected = "test_formula  1. one  2. two  3. three  4. four"
+      assert_equal Hero::Formula[:test_formula].publish.gsub(/\n/, ""), expected
+    end
+
+    it "should support logging" do
+      class TestLogger
+        attr_reader :buffer
+        def info(value)
+          @buffer ||= []
+          @buffer << value
+        end
+      end
+      Hero.logger = TestLogger.new
+      Hero::Formula[:test_formula].add_step(:one) {}
+      Hero::Formula[:test_formula].add_step(:two) {}
+      Hero::Formula[:test_formula].run(:example, :logging => true)
+      assert_equal Hero.logger.buffer.length, 2
+      assert_equal "HERO Formula: test_formula, Step: one, Context: :example, Options: {:logging=>true}", Hero.logger.buffer.first
+      assert_equal "HERO Formula: test_formula, Step: two, Context: :example, Options: {:logging=>true}", Hero.logger.buffer.last
+    end
+
+  end
+
+end
+

data/spec/observer_spec.rb

@@ -0,0 +1,39 @@
+require "spec_helper"
+
+describe "Hero::Observer instance" do
+  include GrumpyOldMan
+
+  it "should support add_step" do
+    step = lambda {}
+    o = Hero::Observer.new(:example)
+    o.add_step(:one, step)
+    assert_equal o.steps.length, 1
+    assert_equal o.steps[0].keys.first, :one
+    assert_equal o.steps[0].values.first, step
+  end
+
+  it "should support properly handle a double add" do
+    step1 = lambda {}
+    step2 = lambda {}
+    o = Hero::Observer.new(:example)
+    o.add_step(:one, step1)
+    o.add_step(:one, step2)
+    assert_equal o.steps.length, 1
+    assert_equal o.steps[0].keys.first, :one
+    assert_equal o.steps[0].values.first, step2
+  end
+
+  it "should properly sort steps based on the order they were added" do
+    o = Hero::Observer.new(:example)
+    o.add_step(:one) {}
+    o.add_step(:two) {}
+    o.add_step(:three) {}
+    o.add_step(:four) {}
+    o.add_step(:one) {}
+    assert_equal o.steps.length, 4
+    assert_equal o.steps[0].keys.first, :two
+    assert_equal o.steps[1].keys.first, :three
+    assert_equal o.steps[2].keys.first, :four
+    assert_equal o.steps[3].keys.first, :one
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,5 @@
+require "pry"
+require "grumpy_old_man"
+Dir[File.join(File.dirname(__FILE__), "..", "lib", "*.rb")].each do |file|
+  require file
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hero
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.4
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-08-23 00:00:00.000000000 Z
+date: 2012-08-24 00:00:00.000000000 Z
 dependencies: []
 description: ! '    Simplify your apps with Hero.
 
@@ -26,7 +26,9 @@ files:
 - Gemfile
 - Gemfile.lock
 - README.md
-- spec/hero_spec.rb
+- spec/formula_spec.rb
+- spec/observer_spec.rb
+- spec/spec_helper.rb
 homepage: http://hopsoft.github.com/hero/
 licenses:
 - MIT

data/spec/hero_spec.rb

@@ -1,70 +0,0 @@
-require "pry"
-require "grumpy_old_man"
-Dir[File.join(File.dirname(__FILE__), "..", "lib", "*.rb")].each do |file|
-  require file
-end
-
-describe Hero::Formula do
-  include GrumpyOldMan
-
-  before :each do
-    Hero::Formula.reset
-  end
-
-  it "should support reset" do
-    Hero::Formula.register(:test_formula)
-    assert_equal Hero::Formula.count, 1
-    Hero::Formula.reset
-    assert_equal Hero::Formula.count, 0
-  end
-
-  it "should support registering a formula" do
-    Hero::Formula.register(:test_formula)
-    assert_equal Hero::Formula.count, 1
-    assert Hero::Formula[:test_formula].is_a? Hero::Formula
-  end
-
-  it "should auto register formulas" do
-    Hero::Formula[:test_formula]
-    assert_equal Hero::Formula.count, 1
-    assert Hero::Formula[:test_formula].is_a? Hero::Formula
-  end
-
-  it "should support registering N number of formulas" do
-    10.times { |i| Hero::Formula.register("example_#{i}") }
-    assert_equal Hero::Formula.count, 10
-  end
-
-  it "should unregister formula observers on reset" do
-    formula = Hero::Formula[:test_formula]
-    assert_equal Hero::Formula.count, 1
-    formula.add_step {}
-    assert_equal formula.count_observers, 1
-    Hero::Formula.reset
-    assert_equal Hero::Formula.count, 0
-    assert_equal formula.count_observers, 0
-  end
-
-  describe "a registered formula" do
-    it "should support adding steps" do
-      Hero::Formula.register(:test_formula)
-      Hero::Formula[:test_formula].add_step { }
-    end
-
-    it "should support notify" do
-      Hero::Formula.register(:test_formula)
-      step_ran = false
-      target = Object.new
-      Hero::Formula[:test_formula].add_step do |t, opts|
-        assert_equal t, target
-        assert_equal opts[:foo], :bar
-        step_ran = true
-      end
-      Hero::Formula[:test_formula].notify(target, :foo => :bar)
-      assert step_ran
-    end
-
-  end
-
-end
-