hero 0.0.4 → 0.0.5

data/README.md

@@ -21,12 +21,12 @@ One that evolved from the real world with concrete use cases and actual producti
 
 ## Why Hero?
 
-* App structure matches the mental map of your business
-* Testable coponents
-* Faster ramp up time for new team members
-* Easily handles changing requirements 
+* It matches the mental map of your business requirements
+* It produces testable components
+* It easily handles changing requirements 
+* It reduces the ramp up time for new team members
 
-### Process Modeling
+## Process Modeling
 
 The problem has always been: **How do you effectively model a business process within your app?**
 
@@ -40,4 +40,141 @@ these processes into managable chunks. And the best part... the components can b
 
 ---
 
-More soon. Stay tuned...
+## Quick Start
+
+```bash
+gem install hero
+```
+
+Lets model a business process for collecting the top news stories from Hacker News, Reddit, & Google and then emailing the results to someone.
+
+Gather News
+
+- Get news from Hacker News
+- Get news from Reddit
+- Get news from Google
+- Email Results
+
+Now that we have the basic requirements, lets model it with Hero.
+
+```ruby
+Hero::Formula[:gather_news].add_step :hacker_news do |context|
+  # make api call
+  # parse results
+  # append results to context
+end
+
+Hero::Formula[:gather_news].add_step :reddit do |context|
+  # make api call
+  # parse results
+  # append results to context
+end
+
+Hero::Formula[:gather_news].add_step :google do |context|
+  # make api call
+  # parse results
+  # append results to context
+end
+
+Hero::Formula[:gather_news].add_step :email do |context|
+  # format news for email
+  # compose the email
+  # send the email
+end
+```
+
+This looks surprising similar to the requirements. 
+In fact we can publish the specification directly from Hero.
+
+```ruby
+puts Hero::Formula[:gather_news].publish
+
+# => gather_news
+#      1. hacker_news
+#      2. reddit
+#      3. google
+#      4. email
+```
+
+Pretty slick.
+Now... lets run the process.
+
+```ruby
+news = {}
+Hero::Formula[:gather_news].run(news)
+```
+
+And we're done.
+
+### Key take aways
+
+- **The implementation aligns perfectly with the requirements.**
+  *This means that developers and business folks can talk the same lingo.*
+
+- **The formula is composed of smaller steps that are interchangable.**
+  *This means we are poised for changing requirements.*
+
+- **Each step implements the interface `def call(context)`**
+  *This means we can create step classes to simplify the app structure.*
+
+## Next Steps
+
+As our app grows in complexity, we should change the steps from blocks to classes.
+Here's an example.
+
+```ruby
+# this
+Hero::Formula[:gather_news].add_step :hacker_news do |context|
+  # make api call
+  # parse results
+  # append results to context
+end
+
+# changes to this
+module GatherNews
+  class HackerNews
+
+    def call(context)
+      # make api call
+      # parse results
+      # append results to context
+    end
+
+  end
+end
+
+Hero::Formula[:gather_news].add_step GatherNews::HackerNews.new
+```
+
+We should also create a directory structure that maps to the business process.
+Something like this.
+
+```bash
+|-app
+  |-formulas
+    |-gather_news
+      |-hacker_news.rb
+      |-reddit.rb
+      |-google.rb
+      |-email.rb
+```
+
+We also need an initializer to set the formula up.
+
+```ruby
+# app/initializer.rb
+Hero::Formula[:gather_news].add_step GatherNews::HackerNews.new
+Hero::Formula[:gather_news].add_step GatherNews::Reddit.new
+Hero::Formula[:gather_news].add_step GatherNews::Google.new
+Hero::Formula[:gather_news].add_step GatherNews::Email.new
+```
+
+Now we have a well structured application that is ready to grow.
+Notice how well organized everything is.
+
+Also note that we can write tests for each step independent of anything else.
+This is an important point and a powerful concept.
+
+## Deep Cuts
+
+Advanced usage coming soon...

data/lib/hero.rb

@@ -4,6 +4,13 @@ end
 
 module Hero
   class << self
+
+    # You can optionally register a Logger with Hero.
+    # If set, a logger.info message will be written for each step called when running Hero::Formulas.
+    #
+    # @example
+    #   Hero.logger = Logger.new(STDOUT)
     attr_accessor :logger
+
   end
 end

data/lib/hero/formula.rb

@@ -60,7 +60,7 @@ module Hero
     def publish
       value = [name]
       steps.each_with_index do |step, index|
-        value << "#{(index + 1).to_s.rjust(3)}. #{step.keys.first}"
+        value << "#{(index + 1).to_s.rjust(3)}. #{step.first}"
       end
       value.join("\n")
     end

data/lib/hero/observer.rb

@@ -1,28 +1,71 @@
 module Hero
+
+  # Hero::Observer is designed to observe Hero::Formulas.
+  # It executes all registered steps whenever Hero::Formula#run is invoked.
+  # A Hero::Formula should only have 1 Hero::Observer attached.
   class Observer
+
+    # The name of the Hero::Formula being observed.
     attr_reader :formula_name
 
+    # @param [Symbol, String] formula_name The name of the Hero::Formula being observed.
     def initialize(formula_name)
       @formula_name = formula_name
     end
 
+    # @return [Array] All registered steps.
     def steps
-      @steps ||= {}
-      @steps.sort{ |a, b| a.last[:index] <=> b.last[:index] }.map{ |k, v| { k => v[:step] } }
+      @steps ||= []
     end
 
+    # Adds a step to be executed when the Hero::Formula is run.
+    #
+    # @example A step must implement the interface
+    #   def call(*args)
+    #
+    # @example More specifically
+    #   def call(context, options={})
+    #
+    # The simplest example being a Proc.
+    #
+    # @note Steps are called in the order they are added. 1st in 1st called
+    #
+    # @example
+    #   add_step(:my_step) do |context, options|
+    #     # logic here...
+    #   end
+    #
+    # @example
+    #   class MyStep
+    #     def self.call(context, options={})
+    #       # logic here...
+    #     end
+    #   end
+    #
+    #   add_step(:my_step, MyStep)
+    #
+    # @param [Symbol, String] name The name of the step.
+    # @param optional [Object] step The step to be executed.
+    # @yield optional [Object, Hash] Uses a passed block as the step to be executed.
     def add_step(name, step=nil, &block)
-      @steps ||= {}
+      steps.delete_if { |s| s.first == name }
       step ||= block if block_given?
-      @steps[name] = { :step => step, :index => @steps.length }
+      steps << [name, step]
     end
 
+    # The callback triggered when Hero::Formula#run is invoked.
+    # This method runs all registered steps in order.
+    #
+    # @note A log message will be written to Hero.logger for each step that is called if Hero.logger has been set.
+    #
+    # @param [Object] context The context to be passed to each step.
+    # @param [Hash] options An option Hash to be passed to each step.
     def update(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}"
+          Hero.logger.info "HERO Formula: #{formula_name}, Step: #{step.first}, Context: #{context.inspect}, Options: #{options.inspect}"
         end
-        step.values.first.call(context, options)
+        step.last.call(context, options)
       end
     end
 

data/spec/observer_spec.rb

@@ -8,8 +8,8 @@ describe "Hero::Observer instance" do
     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
+    assert_equal o.steps[0].first, :one
+    assert_equal o.steps[0].last, step
   end
 
   it "should support properly handle a double add" do
@@ -19,8 +19,8 @@ describe "Hero::Observer instance" do
     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
+    assert_equal o.steps[0].first, :one
+    assert_equal o.steps[0].last, step2
   end
 
   it "should properly sort steps based on the order they were added" do
@@ -31,9 +31,9 @@ describe "Hero::Observer instance" do
     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
+    assert_equal o.steps[0].first, :two
+    assert_equal o.steps[1].first, :three
+    assert_equal o.steps[2].first, :four
+    assert_equal o.steps[3].first, :one
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hero
 version: !ruby/object:Gem::Version
-  version: 0.0.4
+  version: 0.0.5
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-08-24 00:00:00.000000000 Z
+date: 2012-08-25 00:00:00.000000000 Z
 dependencies: []
 description: ! '    Simplify your apps with Hero.