hero 0.0.1 → 0.0.2

data/README.md

@@ -0,0 +1,174 @@
+# Hero
+
+## Its a bird, its a plane, its... its... my Hero
+
+Ever wish that you could unwind the spaghetti and get out of the corner you've been backed into?
+
+### Hero is here to save the day
+
+I've seen my share of poor app structure. 
+Hell, I wrote most of it.
+Whether is fat controllers, giant models with mystery callbacks, or a junk drawer lib directory.
+
+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
+
+The problem has always been: How to effectively model a business process within your app.
+
+Things start simply enough but eventually edge cases force *gothcas* 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.
+
+---
+
+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 business processes which might look 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.
+

data/lib/hero/formula.rb

@@ -0,0 +1,52 @@
+require 'observer'
+require 'singleton'
+require 'forwardable'
+
+module Hero
+  class Formula
+    include Observable
+    include Singleton
+
+    class << self
+      extend Forwardable
+      def_delegator :formulas, :each, :each
+      def_delegator :formulas, :length, :count
+
+      def reset
+        @formulas = {}
+      end
+
+      def [](name)
+        formulas[name] ||= register(name)
+      end
+
+      def register(name)
+        observer = Hero::Observer.new
+        formula = Class.new(Hero::Formula).instance
+        formula.add_observer(observer)
+        formula.instance_eval { @observer = observer }
+        formulas[name] = formula
+      end
+
+      private
+
+      def formulas
+        @formulas ||= {}
+      end
+    end
+
+    def add_step(step=nil, &block)
+      step ||= block if block_given?
+      @observer.steps << step
+    end
+
+    def notify(target=nil, options={})
+      changed
+      notify_observers(target, options)
+    end
+
+    alias :run :notify
+
+  end
+end
+

data/lib/hero.rb

@@ -1,52 +1,3 @@
-require 'observer'
-require 'singleton'
-require 'forwardable'
-
-module Hero
-  class Formula
-    include Observable
-    include Singleton
-
-    class << self
-      extend Forwardable
-      def_delegator :formulas, :each, :each
-      def_delegator :formulas, :length, :count
-
-      def reset
-        @formulas = {}
-      end
-
-      def [](name)
-        formulas[name]
-      end
-
-      def register(name)
-        observer = Hero::Observer.new
-        formula = Class.new(Hero::Formula).instance
-        formula.add_observer(observer)
-        formula.instance_eval { @observer = observer }
-        formulas[name] = formula
-      end
-
-      private
-
-      def formulas
-        @formulas ||= {}
-      end
-    end
-
-    def add_step(step=nil, &block)
-      step ||= block if block_given?
-      @observer.steps << step
-    end
-
-    def notify(target=nil, options={})
-      changed
-      notify_observers(target, options)
-    end
-
-    alias :run :notify
-
-  end
+Dir[File.join(File.dirname(__FILE__), "hero", "*rb")].each do |file|
+  require file
 end
-

data/spec/hero_spec.rb

@@ -24,6 +24,12 @@ describe Hero::Formula do
     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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hero
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-08-22 00:00:00.000000000 Z
+date: 2012-08-23 00:00:00.000000000 Z
 dependencies: []
 description: ! '    Simplify your apps with Hero.
 
@@ -20,10 +20,12 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- lib/hero/formula.rb
+- lib/hero/observer.rb
 - lib/hero.rb
-- lib/hero_observer.rb
 - Gemfile
 - Gemfile.lock
+- README.md
 - spec/hero_spec.rb
 homepage: http://hopsoft.github.com/hero/
 licenses: