newflow 1.0.0

data/lib/newflow.rb

@@ -0,0 +1,95 @@
+require 'logger'
+require 'forwardable'
+
+# Require all the files
+base_dir = File.dirname(__FILE__) + "/newflow"
+Dir["#{base_dir}/*.rb"].each { |f| require f }
+
+# TODO: Allow workflows to identify themselves (for logging and stuffs)
+module Newflow
+  class InvalidStateDefinitionError < ArgumentError; end
+  class InvalidWorkflowStateError < ArgumentError; 
+    def initialize(state)
+      @state = state
+    end
+
+    def message
+      "'#{@state}' is not a valid state"
+    end
+  end
+
+  WITH_SIDE_EFFECTS    = true
+  WITHOUT_SIDE_EFFECTS = false
+
+  def self.included(base)
+    base.send(:include, InstanceMethods)
+    if base.ancestors.map {|a| a.to_s }.include?("ActiveRecord::Base")
+      base.send(:include, ActiveRecordInstantiator)
+    else
+      base.send(:include, NonActiveRecordInstantiator)
+    end
+    base.send(:extend, ClassMethods, Forwardable)
+    base.def_delegators :workflow, :transition!, :transition_once!, :current_state, :current_state=,
+                        :would_transition_to
+  end
+
+  module ActiveRecordInstantiator # TODO: TEST
+    def after_initialize_with_workflow
+      after_initialize_without_workflow if respond_to?(:after_initialize_without_workflow)
+      workflow # This will set the workflow_state
+    end
+    if respond_to?(:after_initialize)
+      alias_method :after_initialize_without_workflow, :after_initialize
+    end
+    alias_method :after_initialize, :after_initialize_with_workflow
+  end
+
+  module NonActiveRecordInstantiator
+    def initialize_with_workflow(*args, &block)
+      initialize_without_workflow(*args, &block)
+      workflow # This will set the workflow_state
+    end
+    alias_method :initialize_without_workflow, :initialize
+    alias_method :initialize, :initialize_with_workflow
+  end
+
+  module InstanceMethods
+    def workflow
+      @workflow ||= Workflow.new(self, self.class.__workflow_definition)
+    end
+  end
+
+  module ClassMethods
+    def define_workflow(&workflow_definition)
+      @__workflow_definition = workflow_definition
+      __define_query_methods(workflow_definition)
+    end
+
+    def __define_query_methods(workflow_definition)
+      @state_catcher = Object.new
+      @state_catcher.instance_variable_set("@states", [])
+      def @state_catcher.states; @states; end
+      def @state_catcher.state(name, *args); @states << name; end
+      @state_catcher.instance_eval &workflow_definition
+      @state_catcher.states.each do |state|
+        self.send(:define_method, "#{state}?") do 
+          workflow.send("#{state}?")
+        end
+      end
+    end
+
+    def __workflow_definition
+      @__workflow_definition
+    end
+  end
+
+  def self.logger
+    return @logger if @logger
+    @logger = if defined?(Rails)
+                Rails.logger
+              else
+                Logger.new(File.open('/dev/null', 'w'))
+              end
+  end
+end
+

data/lib/newflow/state.rb

@@ -0,0 +1,61 @@
+module Newflow
+  class State
+    attr_reader :name, :transitions
+
+    def initialize(name, opts={}, &transitions_block)
+      logger.debug "State.initialize: name=#{name} opts=#{opts.inspect}"
+      @name     = name
+      @opts     = opts
+      @is_start = opts[:start]
+      @is_stop  = opts[:stop]
+      @on_entry = Trigger.new(opts[:on_entry])
+      @transitions = []
+      check_validity
+      instance_eval &transitions_block if transitions_block
+    end
+
+    def transitions_to(target_state, opts={})
+      @transitions << Transition.new(target_state,opts)
+    end
+
+    def run(workflow, do_trigger=Newflow::WITH_SIDE_EFFECTS)
+      return @name unless @transitions
+      # We may want to consider looking at all transitions and letting user know
+      # that you can move in multiple directions
+      transition_to = @transitions.detect { |t| t.can_transition?(workflow) }
+      if transition_to
+        transition_to.trigger!(workflow) if do_trigger # TODO: TEST
+        transition_to.target_state
+      else
+        @name
+      end
+    end
+
+    # TODO: use convention of name == :start instead of a :start opt, not same for stop
+    def start?
+      @opts[:start]
+    end
+
+    def stop?
+      @opts[:stop]
+    end
+
+    def run_on_entry(workflow, do_trigger=Newflow::WITH_SIDE_EFFECTS)
+      @on_entry.run!(workflow) if do_trigger && @on_entry
+    end
+
+    def to_s
+      @name.to_s
+    end
+
+    def logger
+      Newflow.logger
+    end
+
+    private
+      def check_validity
+        raise "State #{name} cannot be both a start and a stop" if start? && stop?
+      end
+  end
+end
+

data/lib/newflow/transition.rb

@@ -0,0 +1,46 @@
+module Newflow
+  class Transition
+    attr_reader :target_state, :predicate, :predicate_name, :trigger
+
+    def initialize(target_state,opts)
+      @target_state = target_state
+      if_meth      = opts[:if]
+      unless_meth  = opts[:unless]
+      @trigger      = Trigger.new(opts[:trigger])
+      logger.debug "State.transitions_to: target_state=#{target_state} if=#{if_meth.inspect} unless=#{unless_meth.inspect} trigger=#{@trigger}"
+      unless @target_state \
+          &&  (if_meth || unless_meth) \
+          && !(if_meth && unless_meth) 
+        raise "You must specify a target state(#@target_state) and (if_method OR unless_method)" 
+      end
+      @predicate_name = (if_meth || "!#{unless_meth}").to_s
+      @predicate = if if_meth
+                     # TODO: be smart
+                     if if_meth.respond_to?(:call)
+                       lambda { |wf| if_meth.call }
+                     else
+                       lambda { |wf| wf.send(if_meth) }
+                     end
+                   else
+                     if unless_meth.respond_to?(:call)
+                       lambda { |wf| !unless_meth.call }
+                     else
+                       lambda { |wf| !wf.send(unless_meth) }
+                     end
+                   end
+    end
+
+    def can_transition?(workflow)
+      predicate.call(workflow)
+    end
+
+    def trigger!(workflow)
+      trigger.run!(workflow)
+    end
+
+    def logger
+      Newflow.logger
+    end
+  end
+end
+

data/lib/newflow/trigger.rb

@@ -0,0 +1,20 @@
+module Newflow
+  class Trigger
+    def initialize(trigger)
+      @trigger = trigger
+    end
+
+    def run!(workflow)
+      return false unless @trigger
+      case @trigger
+      when Symbol
+        workflow.send(@trigger)
+      when Array
+        @trigger.each {|t| Trigger.new(t).run!(workflow) }
+      else
+        @trigger.call
+      end
+    end
+  end
+end
+

data/lib/newflow/workflow.rb

@@ -0,0 +1,103 @@
+module Newflow
+  class Workflow
+    def initialize(extendee, definition)
+      @extendee = extendee
+      construct_workflow!(definition)
+    end
+
+    def validate_workflow!
+      # TODO: Validate that all transitions reach a valid state
+      # TODO: Validate that there is at least one stop state
+      raise InvalidStateDefinitionError.new("#{@extendee.class} needs at least two states") if states.size < 2
+      raise InvalidStateDefinitionError.new("#{@extendee.class} needs a start of the workflow") unless current_state
+    end
+
+    def states
+      @states ||= {}
+    end
+
+    def state(name, opts={}, &block)
+      # TODO: Assert we're not overriding a state
+      states[name] = State.new(name, opts, &block)
+    end
+
+    def construct_workflow!(definition)
+      instance_eval &definition
+      start_state = states.values.detect { |s| s.start? }
+      @extendee.workflow_state ||= start_state.name.to_s if start_state
+      validate_workflow!
+      define_state_query_methods
+      raise InvalidWorkflowStateError.new(current_state) unless states[current_state]
+    end
+
+    def define_state_query_methods
+      states.keys.each do |key|
+        instance_eval <<-EOS
+          def #{key}?; current_state == :#{key}; end
+        EOS
+      end
+    end
+
+    def transition_once!(do_trigger=Newflow::WITH_SIDE_EFFECTS)
+      state = states[current_state]
+      raise InvalidWorkflowStateError.new(current_state) unless state # TODO: TEST
+      target_state = states[state.run(@extendee, do_trigger)]
+      if state != target_state
+        @extendee.workflow_state = target_state.to_s
+        target_state.run_on_entry(@extendee, do_trigger)
+      end
+      target_state
+    end
+
+    def transition!(do_trigger=Newflow::WITH_SIDE_EFFECTS)
+      # TODO: watch out for max # of transits
+      previous_state = current_state
+      previous_states = {}
+      num_transitions = 0
+      begin
+        if previous_states[current_state]
+          raise "Error: possible [infinite] loop in workflow, started in: #{previous_state}, currently in #{current_state}, been through all of (#{previous_states.keys.map(&:to_s).sort.join(", ")})" # TODO: TEST
+        end
+        previous_states[current_state] = true
+        the_state = current_state
+        transition_once!(do_trigger)
+      end while the_state != current_state && states[current_state]
+      previous_state == current_state ? nil : current_state
+    ensure
+      @extendee.workflow_state = previous_state unless do_trigger
+    end
+
+    def would_transition_to
+      transition!(Newflow::WITHOUT_SIDE_EFFECTS)
+    end
+
+    def current_state
+      @extendee.workflow_state.to_sym
+    end
+
+    def current_state=(state)
+      @extendee.workflow_state = state.to_s
+    end
+
+    def to_dotty
+      dot = ""
+      dot << "digraph {\n"
+      states.keys.each { |state_name|
+        state = states[state_name]
+        # it'd be nice to have the current state somehow shown visually
+        shape = "circle"
+        if state_name == current_state
+          puts "setting current shape to doublecircle #{state_name} vs #{current_state}"
+          shape = "doublecircle"
+        end
+        dot << %Q[  "#{state_name}" [ shape = #{shape} ]; \n]
+        state.transitions.each { |transition|
+          dot << "  \"#{state_name}\" -> \"#{transition.target_state}\" [ label = \"#{transition.predicate_name}\" ];\n"
+        }
+      }
+      dot << "}\n"
+      return dot
+    end
+  end
+end
+

data/spec/newflow_spec.rb

@@ -0,0 +1,62 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+describe "An object including Newflow" do
+  before do
+    klass = Class.new do
+      attr_accessor :workflow_state
+      include Newflow
+
+      define_workflow do
+        state :start, :start => true do
+          transitions_to :finish, :if => :go_to_finish?
+        end
+
+        state :finish, :stop => true
+      end
+
+      def go_to_finish?
+        true
+      end
+    end
+    @obj = klass.new
+  end
+
+  it "should begin in start state" do
+    @obj.should be_start
+  end
+
+  it "should stop in the finish state" do
+    @obj.transition!
+    @obj.should be_finish
+  end
+
+  it "should transition once" do
+    @obj.transition_once!
+    @obj.should be_finish
+  end
+
+  it "should have a current state" do
+    @obj.current_state.should == :start
+  end
+
+  it "should have a workflow state" do
+    @obj.workflow_state.should == "start"
+  end
+
+  it "should have a way to manually change the current state" do
+    @obj.current_state = :finish
+    @obj.workflow_state.should == "finish"
+    @obj.should be_finish
+  end
+
+  it "should not eat all missing methods" do
+    lambda { @obj.wammo! }.should raise_error(NoMethodError)
+  end
+
+  it "should keep the state even when the workflow is reset" do
+    @obj.workflow_state = "finish"
+    @obj.instance_variable_set("@workflow", nil)
+    @obj.should be_finish
+  end
+end
+

data/spec/newflow_state_spec.rb

@@ -0,0 +1,72 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+describe "A valid start state" do
+  before do
+    @name  = :start
+    @workflow = mock("workflow")
+    @state = Newflow::State.new(@name, :start => true) do
+      transitions_to :finish, :if => :go_to_finish?
+    end
+  end
+
+  it "should have a name" do
+    @state.name.should == @name
+  end
+
+  it "should be a start" do
+    @state.should be_start
+  end
+
+  it "should turn itself into a string" do
+    @state.to_s.should == @name.to_s
+  end
+
+  it "should should not bomb when running on entry" do
+    lambda { @state.run_on_entry(@extendee) }.should_not raise_error
+  end
+
+  it "should return the transition state when the predicate is true" do
+    @workflow.should_receive(:go_to_finish?).and_return true
+    @state.run(@workflow).should == :finish
+  end
+
+  it "should return the its own state when the predicate is false" do
+    @workflow.should_receive(:go_to_finish?).and_return false
+    @state.run(@workflow).should == :start
+  end
+end
+
+describe "A state with on_entry" do
+  before do
+    @name = :start
+    @extendee = mock("extendee")
+    @state = Newflow::State.new(@name, :on_entry => :make_pizza)
+  end
+
+  it "should run on entry when triggers are on (default)" do
+    @extendee.should_receive(:make_pizza)
+    @state.run_on_entry(@extendee)
+  end
+
+  it "should not run on entry when triggers are off" do
+    @extendee.should_not_receive(:make_pizza)
+    @state.run_on_entry(@extendee, Newflow::WITHOUT_SIDE_EFFECTS) 
+  end
+end
+
+describe "A valid stop state" do
+  before do
+    @name  = :stop
+    @state = Newflow::State.new(@name, :stop => true)
+  end
+
+  it "should be a stop" do
+    @state.should be_stop
+  end
+end
+
+describe "Invalid states" do
+  it "should not have both a start and a stop" do
+    lambda { @state = Newflow::State.new(:hi, :start => true, :stop => true) }.should raise_error
+  end
+end

data/spec/newflow_transition_spec.rb

@@ -0,0 +1,109 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+describe "An :if symbol transition with a symbol trigger" do
+  before do
+    @workflow = mock("workflow")
+    @transition = Newflow::Transition.new(:target_state, :if => :predicate?, :trigger => :some_action)
+  end
+
+  it "should not be able to transition if predicate is false" do
+    @workflow.should_receive(:predicate?).and_return false
+    @transition.can_transition?(@workflow).should be_false
+  end
+
+  it "should be able to transition if predicate is true" do
+    @workflow.should_receive(:predicate?).and_return true
+    @transition.can_transition?(@workflow).should be_true
+  end
+
+  it "should call the trigger if requested" do
+    @workflow.should_receive(:some_action)
+    @transition.trigger!(@workflow)
+  end
+
+  it "should have a predicate name" do
+    @transition.predicate_name.should == "predicate?"
+  end
+
+  it "should have a target state" do
+    @transition.target_state.should == :target_state
+  end
+end
+
+describe "An :unless symbol transition with a proc trigger" do
+  before do
+    @workflow = mock("workflow")
+    @trigger_ran = false
+    @trigger  = lambda { @trigger_ran = true }
+    @transition = Newflow::Transition.new(:target_state, :unless => :predicate?, :trigger => @trigger)
+  end
+
+  it "should not be able to transition if predicate is true" do
+    @workflow.should_receive(:predicate?).and_return true
+    @transition.can_transition?(@workflow).should be_false
+  end
+
+  it "should be able to transition if predicate is false" do
+    @workflow.should_receive(:predicate?).and_return false
+    @transition.can_transition?(@workflow).should be_true
+  end
+
+  it "should call the trigger when requested" do
+    @transition.trigger!(@workflow)
+    @trigger_ran.should be_true
+  end
+
+  it "should have a predicate name" do
+    @transition.predicate_name.should == "!predicate?"
+  end
+end
+
+describe "An :if proc transition with no trigger" do
+  before do
+    @workflow = mock("workflow")
+    @if_proc  = lambda { @predicate_value }
+    @transition = Newflow::Transition.new(:target_state, :if => @if_proc)
+  end
+
+  it "should not be able to transition if predicate is false" do
+    @predicate_value = false
+    @transition.can_transition?(@workflow).should be_false
+  end
+
+  it "should be able to transition if predicate is true" do
+    @predicate_value = true
+    @transition.can_transition?(@workflow).should be_true
+  end
+
+  it "should do nothing when triggered" do
+    lambda { @transition.trigger!(@workflow) }.should_not raise_error
+  end
+end
+
+describe "An :unless proc transition with no trigger" do
+  before do
+    @workflow    = mock("workflow")
+    @unless_proc = lambda { @predicate_value }
+    @transition  = Newflow::Transition.new(:target_state, :unless => @unless_proc)
+  end
+
+  it "should not be able to transition if predicate is true" do
+    @predicate_value = true
+    @transition.can_transition?(@workflow).should be_false
+  end
+
+  it "should be able to transition if predicate is false" do
+    @predicate_value = false
+    @transition.can_transition?(@workflow).should be_true
+  end
+end
+
+describe "Invalid triggers" do
+  it "should not be valid without an if or unless" do
+    lambda { @transition = Newflow::Transition.new(:target_state) }.should raise_error
+  end
+
+  it "should not be valid with an if and an unless" do
+    lambda { @transition = Newflow::Transition.new(:target_state, :unless => :unless, :if => :if) }.should raise_error
+  end
+end

data/spec/newflow_trigger_spec.rb

@@ -0,0 +1,50 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+describe "An empty trigger" do
+  before do
+    @extendee = mock("extendee")
+    @trigger = Newflow::Trigger.new(nil)
+  end
+
+  it "should do nothing when running" do
+    lambda { @trigger.run!(@extendee) }.should_not raise_error
+  end
+end
+
+describe "A symbol trigger" do
+  before do
+    @extendee = mock("extendee")
+    @trigger = Newflow::Trigger.new(:make_pizza)
+  end
+
+  it "should run the trigger on the workflow" do
+    @extendee.should_receive(:make_pizza)
+    @trigger.run!(@extendee)
+  end
+end
+
+describe "An array trigger" do
+  before do
+    @extendee = mock("extendee")
+    @trigger = Newflow::Trigger.new([:make_pizza, :make_cake])
+  end
+
+  it "should run the triggers on the workflow" do
+    @extendee.should_receive(:make_pizza)
+    @extendee.should_receive(:make_cake)
+    @trigger.run!(@extendee)
+  end
+end
+
+describe "A lambda trigger" do
+  before do
+    @extendee = mock("extendee")
+    @trigger = Newflow::Trigger.new(lambda { @extendee.make_pizza })
+  end
+
+  it "should run the triggers on the workflow" do
+    @extendee.should_receive(:make_pizza)
+    @trigger.run!(@extendee)
+  end
+end
+

data/spec/newflow_workflow_spec.rb

@@ -0,0 +1,97 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+describe "A workflow" do
+  before do
+    @klass = Class.new do
+      attr_accessor :workflow_state
+    end
+    @obj = @klass.new
+  end
+
+  describe "A workflow with no states" do
+    before do
+      @definition = lambda {}
+    end
+
+    it "should raise an error on creation" do
+      lambda { Newflow::Workflow.new(@obj, @definition) }.should raise_error(Newflow::InvalidStateDefinitionError)
+    end
+  end
+
+  describe "A workflow with one state" do
+    before do
+      @definition = lambda {
+        state :start
+      }
+    end
+
+    it "should raise an error on creation" do
+      lambda { Newflow::Workflow.new(@obj, @definition) }.should raise_error(Newflow::InvalidStateDefinitionError)
+    end
+  end
+
+  describe "The minimal valid workflow" do
+    before do
+      @definition = lambda {
+        state :start, :start => true do
+          transitions_to :finish, :if => :go_to_finish?
+        end
+
+        state :finish, :on_entry => :make_pizza, :stop => true
+      }
+
+      @klass.send(:define_method, :go_to_finish?) do
+        true
+      end
+      @klass.send(:define_method, :make_pizza) do
+        "yum"
+      end
+      @workflow = Newflow::Workflow.new(@obj, @definition)
+    end
+
+    it "should begin in start state" do
+      @workflow.should be_start
+      @obj.workflow_state.should == "start"
+    end
+
+    it "should trigger the on_entry when going to finish" do
+      @obj.should_receive :make_pizza
+      @workflow.transition!
+    end
+
+    it "should be able to transition to the finish state" do
+      state = @workflow.would_transition_to
+      state.should == :finish
+      @workflow.should be_start
+    end
+
+    it "should stop in the finish state" do
+      @workflow.transition!
+      @workflow.should be_finish
+      @obj.workflow_state.should == "finish"
+    end
+  end
+
+  describe "A workflow with an invalid object" do
+    before do
+      @definition = lambda {
+        state :start, :start => true do
+          transitions_to :finish, :if => :go_to_finish?
+        end
+
+        state :finish, :stop => true
+      }
+
+      @klass.send(:define_method, :go_to_finish?) do
+        true
+      end
+      @obj.workflow_state = "invalid"
+    end
+
+    it "should raise an error on instantiation" do
+      lambda { Newflow::Workflow.new(@obj, @definition) }.should raise_error(Newflow::InvalidWorkflowStateError)
+    end
+  end
+end
+
+

data/spec/spec_helper.rb

@@ -0,0 +1,5 @@
+require 'rubygems'
+require 'spec'
+require 'ruby-debug'
+require File.dirname(__FILE__) + "/../lib/newflow"
+

metadata

@@ -0,0 +1,70 @@
+--- !ruby/object:Gem::Specification 
+name: newflow
+version: !ruby/object:Gem::Version 
+  version: 1.0.0
+platform: ruby
+authors: 
+- Trotter Cashion
+- Kyle Burton
+- Aaron Feng
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-10-02 00:00:00 -04:00
+default_executable: 
+dependencies: []
+
+description: |
+  Newflow provides a way to add workflows to existing objects. It uses
+  a simple dsl to add guards and triggers to states and their transitions.
+
+email: cashion@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- lib/newflow/state.rb
+- lib/newflow/transition.rb
+- lib/newflow/trigger.rb
+- lib/newflow/workflow.rb
+- lib/newflow.rb
+- spec/newflow_spec.rb
+- spec/newflow_state_spec.rb
+- spec/newflow_transition_spec.rb
+- spec/newflow_trigger_spec.rb
+- spec/newflow_workflow_spec.rb
+- spec/spec_helper.rb
+has_rdoc: true
+homepage: http://trottercashion.com
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: Add workflows (state transitions) to objects.
+test_files: []
+