hero 0.0.5 → 0.0.6

data/lib/hero/formula.rb

@@ -5,31 +5,65 @@ require File.join(File.dirname(__FILE__), "observer")
 
 module Hero
 
+  # Represents a business process that can be easily modeled and implemented.
+  #
+  # The idea is to encourage implementations that more closely resemble
+  # business requirements in order to reduce the dissonance
+  # that is typical between business nomenclature and actual implementation.
+  #
+  # Additional benefits include:
+  # * Composable units of code which support changing requirements
+  # * Testable components
+  # * Simplified implementation
+  #
+  # @example A basic example.
+  #   Hero::Formula[:checkout].add_step(:total) do |context, options|
+  #     # total order (apply discounts etc...)
+  #   end
+  #
+  #   Hero::Formula[:checkout].add_step(:charge) do |context, options|
+  #     # charge for order (handle failure and timeouts gracefully etc...)
+  #   end
+  #
+  #   Hero::Formula[:checkout].add_step(:complete) do |context, options|
+  #     # handle shipping arrangements and follow up email etc...
+  #   end
   class Formula
 
     # Class attributes & methods ==============================================
     class << self
       extend Forwardable
+
+      # Iterates over all registered formulas.
       def_delegator :formulas, :each, :each
+
+      # Indicates the total number of registered formulas.
       def_delegator :formulas, :length, :count
 
-      def publish
+      # Returns a string representation of all registered formulas.
+      def to_s
         value = []
-        each do |name, formula|
-          value << formula.publish
-        end
+        each { |name, formula| value << formula.to_s }
         value.join("\n\n")
       end
 
+      # Removes all registered formulas.
       def reset
         formulas.values.each { |f| f.delete_observers }
         @formulas = {}
       end
 
+      # Returns the named formula.
+      # @note Implicitly registers the formula if it has not already been registered.
+      # @param [Symbol, String] name The name of the formula.
+      # @return Hero::Formula
       def [](name)
         formulas[name] ||= register(name)
       end
 
+      # Registers a formula an prepares it to receive steps.
+      # @param [Symbol, String] name The name of the formula.
+      # @return Hero::Formula
       def register(name)
         observer = Hero::Observer.new(name)
         formula = Class.new(Hero::Formula).instance
@@ -43,6 +77,7 @@ module Hero
 
       private
 
+      # Returns a Hash of all registered formulas.
       def formulas
         @formulas ||= {}
       end
@@ -53,18 +88,47 @@ module Hero
     include Observable
     include Singleton
 
-    attr_reader :name, :observer
+    # The name of this formula.
+    attr_reader :name
+
+    # The observer attached to this formula.
+    attr_reader :observer
+
+    # All registered steps.
     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.first}"
-      end
-      value.join("\n")
-    end
+    # Adds a step to be executed when this formula is run.
+    # @note Steps are called in the order they are added. 1st in 1st invoked.
+    #
+    # @example A step must implement the interface.
+    #   def call(*args)
+    #
+    #   # or more specifically
+    #   def call(context, options={})
+    #
+    # @example Add a step using a block.
+    #   add_step(:my_step) do |context, options|
+    #     # logic here...
+    #   end
+    #
+    # @example Add a step using an Object.
+    #   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.
+    # @block optional [Object] A block to use as the step to be executed.
+    def_delegator :observer, :add_step, :add_step
 
+    # Observable notify implementation.
+    # Invokes #update on all observers.
+    # @param optional [Object] context The context to be passed to each step.
+    # @param optional [Hash] options An option Hash to be passed to each step.
     def notify(context=nil, options={})
       changed
       notify_observers(context, options)
@@ -72,6 +136,20 @@ module Hero
 
     alias :run :notify
 
+    # Returns a String representation of the formula.
+    # @example
+    #   Hero::Formula[:example].add_step(:one) {}
+    #   Hero::Formula[:example].add_step(:two) {}
+    #   Hero::Formula[:example].add_step(:three) {}
+    #   Hero::Formula[:example].to_s # => "example\n  1. one\n  2. two\n  3. three"
+    def to_s
+      value = [name]
+      steps.each_with_index do |step, index|
+        value << "#{(index + 1).to_s.rjust(3)}. #{step.first}"
+      end
+      value.join("\n")
+    end
+
   end
 end
 

data/lib/hero/observer.rb

@@ -19,23 +19,20 @@ module Hero
     end
 
     # Adds a step to be executed when the Hero::Formula is run.
+    # @note Steps are called in the order they are added. 1st in 1st invoked.
     #
-    # @example A step must implement the interface
+    # @example A step must implement the interface.
     #   def call(*args)
     #
-    # @example More specifically
+    #   # or 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
+    # @example Add a step using a block.
     #   add_step(:my_step) do |context, options|
     #     # logic here...
     #   end
     #
-    # @example
+    # @example Add a step using an Object.
     #   class MyStep
     #     def self.call(context, options={})
     #       # logic here...
@@ -46,7 +43,7 @@ module Hero
     #
     # @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.
+    # @block optional [Object] A block to use as the step to be executed.
     def add_step(name, step=nil, &block)
       steps.delete_if { |s| s.first == name }
       step ||= block if block_given?
@@ -58,9 +55,9 @@ module Hero
     #
     # @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={})
+    # @param optional [Object] context The context to be passed to each step.
+    # @param optional [Hash] options An option Hash to be passed to each step.
+    def update(context=nil, options={})
       steps.each do |step|
         if Hero.logger
           Hero.logger.info "HERO Formula: #{formula_name}, Step: #{step.first}, Context: #{context.inspect}, Options: #{options.inspect}"

data/spec/formula_spec.rb

@@ -54,7 +54,7 @@ describe Hero::Formula do
     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
+    assert_equal Hero::Formula.to_s.gsub(/\n/, ""), expected
   end
 
   describe "a registered formula" do
@@ -112,7 +112,7 @@ describe Hero::Formula do
       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
+      assert_equal Hero::Formula[:test_formula].to_s.gsub(/\n/, ""), expected
     end
 
     it "should support logging" do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hero
 version: !ruby/object:Gem::Version
-  version: 0.0.5
+  version: 0.0.6
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-08-25 00:00:00.000000000 Z
+date: 2012-08-26 00:00:00.000000000 Z
 dependencies: []
 description: ! '    Simplify your apps with Hero.
 
@@ -55,3 +55,4 @@ signing_key:
 specification_version: 3
 summary: Business process modeling for the Rubyist
 test_files: []
+has_rdoc: