methodical 0.0.1

data/lib/methodical/executable.rb

@@ -0,0 +1,61 @@
+module Methodical
+  module Executable
+    attr_writer   :raise_on_error
+
+    # Default exception handling:
+    # * RuntimeErrors are considered failures. The exception will be captured
+    #   and not re-raised.
+    # * StandardErrors are considered indicative of a programming error in the
+    #   action.  The action will be marked as bad and failure recorded; but the
+    #   exception will not be re-thrown.
+    # * Exceptions not caught by the other cases are considered fatal errors.
+    #   The step will be marked bad and the error recorded, and the exception
+    #   will then be re-raised.
+    def execute!(baton=nil, raise_on_error=raise_on_error?)
+      disposition = catch_disposition do
+        call(baton, self)
+      end
+    rescue RuntimeError => error
+      disposition = save_and_return_disposition(:failed, error.message, nil, error)
+      raise if raise_on_error
+      disposition
+    rescue StandardError => error
+      disposition = save_and_return_disposition(:bad, error.message, nil, error)
+      raise if raise_on_error
+      disposition
+    rescue Exception => error
+      save_and_return_disposition(:bad, error.message, nil, error)
+      raise
+    else
+      save_and_return_disposition(
+        disposition.status, 
+        disposition.explanation, 
+        disposition.result,
+        nil, 
+        disposition.details)
+    end
+
+    def catch_disposition
+      result = catch(:methodical_disposition) do
+        yield
+      end
+      Methodical::Disposition(result)
+    end
+
+    def raise_on_error?
+      defined?(@raise_on_error) ? @raise_on_error : false
+    end
+
+    private
+
+    def save_and_return_disposition(status, explanation, result, error, details="")
+      details = if details.blank? && error
+                  error.backtrace.join("\n")
+                else
+                  details
+                end
+      update!(status, explanation, result, error, details)
+    end
+
+  end
+end

data/lib/methodical/modifier.rb

@@ -0,0 +1,43 @@
+require 'delegate'
+require 'methodical/executable'
+
+module Methodical
+  class Modifier < SimpleDelegator
+    include Executable
+
+    def initialize(name, action_item=nil, &block)
+      @name        = name
+      __setobj__(action_item)
+      @block       = block
+    end
+
+    def to_s
+      "<#{@name}>(#{action_item.to_s})"
+    end
+
+    def call(baton=nil, raise_on_error=false)
+      @block.call(action_item, baton)
+    end
+
+    def <<(rhs)
+      if self.action_item
+        self.action_item << rhs
+      else
+        self.action_item = rhs
+      end
+      self
+    end
+
+    if RUBY_VERSION=='1.8.6'
+      def clone
+        the_clone = Object.instance_method(:clone).bind(self).call
+        the_clone.__setobj__(__getobj__.clone)
+        the_clone
+      end
+    end
+
+    alias_method :action_item, :__getobj__
+    alias_method :action_item=, :__setobj__
+
+  end
+end

data/lib/methodical/simple_action_item.rb

@@ -0,0 +1,30 @@
+require 'methodical/action_item'
+
+module Methodical
+  class SimpleActionItem < ActionItem
+    extend Forwardable
+
+    def initialize(title, callable=nil, &block)
+      unless(!!callable ^ !!block)
+        raise ArgumentError, "Either a callable or a block must be provided"
+      end
+      @block       = callable || block
+      super(title)
+    end
+
+    def call(baton, step)
+      @block.call(baton, step)
+    end
+
+    def ==(other)
+      self.block.eql?(other.block)
+    end
+
+    protected
+    
+    attr_reader :block
+
+    private
+
+  end
+end

data/lib/methodical/walkthrough.rb

@@ -0,0 +1,143 @@
+require 'delegate'
+require 'forwardable'
+
+module Methodical
+  class Walkthrough < DelegateClass(Array)
+    extend Forwardable
+
+    attr_reader :checklist
+    attr_reader :next_step_index
+    attr_reader :last_step_index
+    attr_reader :baton
+    attr_reader :index
+    attr_reader :decisive_index
+
+    def_delegators :checklist, :title
+
+    def initialize(checklist, baton=nil)
+      @checklist       = checklist
+      @continue        = true
+      @baton           = baton
+      @index           = 0
+      @decisive_index  = nil
+      @halted          = false
+      @started         = false
+      super(Array.new(checklist.map{|ai| ai.clone}))
+      each do |step|
+        step.walkthrough = self
+      end
+    end
+
+    def perform!(baton=@baton, raise_on_error=false, &block)
+      @baton  = baton
+      until done?
+        self.next!(baton, raise_on_error, &block)
+      end
+    end
+
+    def next!(baton=@baton, raise_on_error=false)
+      raise "Already performed" if done?
+
+      @started = true
+
+      action_item = fetch(index)
+      yield(self, index, action_item, baton) if block_given?
+
+      execute_or_update_step(action_item, baton, raise_on_error)
+
+      @decisive_index = index if action_item.decisive?
+      @halted         = true if action_item.halted?
+
+      yield(self, index, action_item, baton) if block_given?
+      advance!
+    end
+
+    def inspect
+      "##<#{self.class.name}:#{title}:#{object_id}>"
+    end
+
+    def basic_report
+      inject(""){|report, action_item| 
+        report << action_item.synopsis << "\n"
+      }
+    end
+
+    def failed_steps
+      find_all{|step| step.failed?}
+    end
+
+    def decisive_step
+      decided? ? fetch(decisive_index) : nil
+    end
+
+    def status
+      if !started? then :not_started
+      elsif !decided? then :in_progress
+      elsif succeeded? then :succeeded
+      else  :failed
+      end
+    end
+
+    def failed?
+      decided? && !decisive_step.done_and_ok?
+    end
+    
+    def succeeded?
+      return true if empty?
+      decided? && decisive_step.done_and_ok?
+    end
+
+    def done?
+      index >= size
+    end
+    alias_method :finished?, :done?
+
+    def decided?
+      !!decisive_index
+    end
+
+    def halted?
+      @halted
+    end
+
+    def in_progress?
+      started? && !done?
+    end
+
+    def started?
+      @started
+    end
+
+    private
+
+    def advance!
+      @index += 1
+      if @index >= size
+        @decisive_index ||= (size - 1)
+      end
+    end
+
+    def continue?
+      !done? && !halted?
+    end
+
+    def execute_or_update_step(step, baton, raise_on_error)
+      if decided?
+        step.ignored = true
+      end
+
+      if continue?
+        step.raise_on_error = raise_on_error
+        step.execute!(baton, raise_on_error)
+      else
+        reason = if failed?
+                   "Run aborted by prior step"
+                 else
+                   "Satisfied by prior step"
+                 end
+        step.update!(:skipped, reason, nil)
+      end
+    end
+
+  end
+end

data/spec/spec.opts

@@ -0,0 +1 @@
+--color

data/spec/spec_helper.rb

@@ -0,0 +1,9 @@
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+require 'methodical'
+require 'spec'
+require 'spec/autorun'
+
+Spec::Runner.configure do |config|
+  config.mock_with :mocha
+end

data/test/methodical/checklist_test.rb

@@ -0,0 +1,79 @@
+require File.expand_path("../test_helper", File.dirname(__FILE__))
+require 'methodical/checklist'
+require 'methodical/dsl'
+
+class ActionItemTest < Test::Unit::TestCase
+  include Methodical::DSL
+
+  context "with no action items" do
+    specify "has a title" do
+      it = Methodical::Checklist.new("My Checklist")
+      assert_equal "My Checklist", it.title
+    end
+
+    specify "knows it has no items" do
+      it = Methodical::Checklist.new("My Checklist")
+      assert_equal 0, it.size
+    end
+
+  end
+
+  context "with three action items" do
+    specify "knows it has three items" do
+      it = Methodical::Checklist.new("My Checklist")
+      it << stub("ActionItem 1")
+      it << stub("ActionItem 2")
+      it << stub("ActionItem 3")
+      assert_equal 3, it.size
+    end
+  end
+
+  context "#perform_walkthrough" do
+    specify "returns step list as Walkthrough object" do
+      it = Methodical::Checklist.new("My Checklist")
+      assert_kind_of Methodical::Walkthrough, it.perform_walkthrough!
+    end
+
+    specify "creates, performs, and returns a new walkthrough" do
+      sensor = :unset
+      walkthrough = stub("Walkthrough")
+      it = Methodical::Checklist.new("My Checklist")
+
+      Methodical::Walkthrough.expects(:new).with(it).returns(walkthrough)
+      walkthrough.expects(:perform!).with("BATON", false).yields(42)
+
+      result = it.perform_walkthrough!("BATON") do |*args| 
+        sensor = args
+      end
+      assert_equal [42], sensor
+      assert_same  walkthrough, result
+    end
+  end
+
+  context "#new_walkthrough" do
+    specify "returns a Walkthrough" do
+      it = Methodical::Checklist.new("My Checklist")
+      assert_kind_of Methodical::Walkthrough, it.new_walkthrough
+    end
+
+    specify "populates the returned walkthrough" do
+      it = Methodical::Checklist.new("My Checklist")
+      it << stub("ActionItem 1", :clone => a1 = stub_everything("ActionItem 1b"))
+      it << stub("ActionItem 2", :clone => a2 = stub_everything("ActionItem 2b") )
+      it << stub("ActionItem 3", :clone => a3 = stub_everything("ActionItem 3b"))
+      assert_equal [a1, a2, a3], it.new_walkthrough
+    end
+
+    specify "does not execute the returned walkthrough" do
+      it = Methodical::Checklist.new("My Checklist")
+      it << stub("ActionItem 1", :clone => a1 = stub_everything("ActionItem 1b"))
+      a1.expects(:call).never
+      it.new_walkthrough
+    end
+
+    specify "returns a walkthrough which points back to the checklist" do
+      it = Methodical::Checklist.new("My Checklist")
+      assert_same it, it.new_walkthrough.checklist
+    end
+  end
+end

data/test/methodical/disposition_test.rb

@@ -0,0 +1,120 @@
+require File.expand_path("../test_helper", File.dirname(__FILE__))
+require 'methodical/disposition'
+
+class DispositionTest < Test::Unit::TestCase
+  def self.test_predicate(predicate, truth_table)
+    context "##{predicate}" do
+      truth_table.each_pair do |status, expected|
+        specify "#{expected} when #{status.inspect}" do
+          assert_equal expected, Methodical::Disposition(status, "", nil).send(predicate)
+        end
+      end
+    end
+  end
+
+  specify "aliases memento to result" do
+    it = Methodical::Disposition.new([:in_progress, "", nil])
+    it.result = 42
+    assert_equal 42, it.memento
+    it.memento = 24
+    assert_equal 24, it.result
+  end
+  
+  test_predicate(:ok?, {
+      :succeeded   => true,
+      :sufficient  => true,
+      :not_started => true,
+      :in_progress => true,
+      :finish      => true,
+      :skipped     => true,
+      :failed      => false,
+      :bad         => false,
+      :abort       => false
+    })
+
+  test_predicate(:succeeded?, {
+      :succeeded   => true,
+      :sufficient  => true,
+      :not_started => false,
+      :in_progress => false,
+      :finish      => true,
+      :skipped     => false,
+      :failed      => false,
+      :bad         => false,
+      :abort       => false
+    })
+
+  test_predicate(:bad?, {
+      :succeeded   => false,
+      :sufficient  => false,
+      :not_started => false,
+      :in_progress => false,
+      :finish      => false,
+      :skipped     => false,
+      :failed      => false,
+      :bad         => true,
+      :abort       => false
+    })
+
+  test_predicate(:done?, {
+      :succeeded   => true,
+      :sufficient  => true,
+      :not_started => false,
+      :in_progress => false,
+      :finish      => true,
+      :skipped     => true,
+      :failed      => true,
+      :bad         => true,
+      :abort       => true
+    })
+
+  test_predicate(:skipped?, {
+      :succeeded   => false,
+      :sufficient  => false,
+      :not_started => false,
+      :in_progress => false,
+      :finish      => false,
+      :skipped     => true,
+      :failed      => false,
+      :bad         => false,
+      :abort       => false
+    })
+
+  test_predicate(:continuable?, {
+      :succeeded   => true,
+      :sufficient  => true,
+      :finish      => false,
+      :not_started => true,
+      :in_progress => true,
+      :skipped     => true,
+      :failed      => true,
+      :bad         => true,
+      :abort       => false
+    })
+
+  test_predicate(:decisive?, {
+      :succeeded   => false,
+      :sufficient  => true,
+      :finish      => true,
+      :not_started => false,
+      :in_progress => false,
+      :skipped     => false,
+      :failed      => true,
+      :bad         => true,
+      :abort       => true
+    })
+
+  test_predicate(:done_and_ok?, {
+      :succeeded   => true,
+      :sufficient  => true,
+      :finish      => true,
+      :not_started => false,
+      :in_progress => false,
+      :skipped     => true,
+      :failed      => false,
+      :bad         => false,
+      :abort       => false
+    })
+
+end
+