multiflow 1.0.0

data/lib/multiflow.rb

@@ -0,0 +1,121 @@
+require 'active_support'
+require 'active_support/inflector'
+
+module Multiflow
+  extend ActiveSupport::Concern
+
+  included do
+    Multiflow::Persistence.load!(self)
+  end
+
+  def self.persistence
+    @@persistence ||= nil
+  end
+
+  def self.persistence=(persistence)
+    @@persistence = persistence
+  end
+
+  module ClassMethods
+    def machines
+      @machines ||= []
+    end
+
+    def stateflow(&block)
+      @machines ||= []
+
+      machine = Multiflow::Machine.new(&block)
+      @machines << machine
+
+      reader     = :"machine_#{machine.state_column}"
+      state      = :"current_#{machine.state_column}"
+      mach_ivar  = :"@#{reader}"
+      state_ivar = :"@#{state}"
+
+      if respond_to?(reader)
+        raise ArgumentError, "Machine for #{machine.state_column} is already defined"
+      end
+
+      define_method(reader) do
+        self.class.send reader
+      end
+
+      define_singleton_method(reader) do
+        instance_variable_get(mach_ivar)
+      end
+
+      instance_variable_set(mach_ivar, machine)
+
+      define_method(state) do
+        state = instance_variable_get(state_ivar)
+
+        if state.nil?
+          loaded = load_from_persistence(machine)
+          if loaded.nil?
+            state = machine.initial_state
+          else
+            state = machine.states[loaded.to_sym]
+          end
+
+          instance_variable_set(state_ivar, state)
+        end
+
+        state
+      end
+
+      define_method("set_#{state}") do |state, options = {}|
+        save_to_persistence(machine, state.name.to_s, options)
+        instance_variable_set(state_ivar, state)
+      end
+
+      machine.states.values.each do |state|
+        state_name = state.name
+
+        define_method(:"#{state_name}?") do
+          state_name == send(:"current_#{machine.state_column}").name
+        end
+
+        if machine.create_scopes?
+          add_scope(machine, state)
+        end
+      end
+
+      machine.events.keys.each do |key|
+        define_method(key.to_sym) do
+          fire_event(machine, key, :save => false)
+        end
+
+        define_method(:"#{key}!") do
+          fire_event(machine, key, :save => true)
+        end
+      end
+    end
+  end
+
+  def machines
+    self.class.machines
+  end
+
+  private
+
+  def fire_event(machine, event_name, options = {})
+    event = machine.events[event_name.to_sym]
+    raise Multiflow::NoEventFound.new("No event matches #{event_name}") if event.nil?
+
+    current_state = send :"current_#{machine.state_column}"
+
+    state = event.fire(machine, current_state, self, options)
+
+    unless state.nil?
+      send :"set_current_#{machine.state_column}", state, options
+    end
+  end
+end
+
+require 'multiflow/machine'
+require 'multiflow/state'
+require 'multiflow/event'
+require 'multiflow/transition'
+require 'multiflow/persistence'
+require 'multiflow/exception'
+require 'multiflow/railtie' if defined?(Rails)

data/multiflow.gemspec

@@ -0,0 +1,24 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = "multiflow"
+  s.version = "1.0.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 1.2")
+  s.authors = ["Ryan Oberholzer", "Sergey Gridasov"]
+  s.date = "2013-03-06"
+  s.description = "State machine that allows dynamic transitions for business workflows"
+  s.email = ["ryan@platform45.com", "grindars@gmail.com"]
+  s.files         = `git ls-files`.split($/)
+  s.executables   = s.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  s.test_files    = s.files.grep(%r{^(test|spec|features)/})
+  s.require_paths = ["lib"]
+  s.homepage = "https://github.com/grindars/multiflow"
+  s.rubygems_version = "2.0.0"
+  s.summary = "State machine that allows dynamic transitions for business workflows"
+
+  s.add_runtime_dependency("activesupport", ">= 0")
+  s.add_development_dependency("rspec", ">= 2.0.0")
+  s.add_development_dependency("activerecord", ">= 0")
+  s.add_development_dependency("sqlite3-ruby", ">= 0")
+end

data/spec/mongoid.yml

@@ -0,0 +1,6 @@
+test:
+  sessions:
+    default:
+      database: stateflow_test
+      hosts:
+        - localhost:27017

data/spec/orm/activerecord_spec.rb

@@ -0,0 +1,209 @@
+require 'spec_helper'
+require 'active_record'
+
+Multiflow.persistence = :active_record
+
+# change this if sqlite is unavailable
+dbconfig = {
+  :adapter => 'sqlite3',
+  :database => ':memory:'
+}
+
+ActiveRecord::Base.establish_connection(dbconfig)
+ActiveRecord::Migration.verbose = false
+
+class TestMigration < ActiveRecord::Migration
+  def self.up
+    create_table :active_record_robots, :force => true do |t|
+      t.column :state, :string
+      t.column :name, :string
+    end
+
+    create_table :active_record_no_scope_robots, :force => true do |t|
+      t.column :state, :string
+      t.column :name, :string
+    end
+  end
+
+  def self.down
+    drop_table :active_record_robots
+    drop_table :active_record_no_scope_robots
+  end
+end
+
+class ActiveRecordRobot < ActiveRecord::Base
+  include Multiflow
+
+  stateflow do
+    initial :red
+
+    state :red, :green
+
+    event :change do
+      transitions :from => :red, :to => :green
+    end
+  end
+end
+
+class ActiveRecordNoScopeRobot < ActiveRecord::Base
+  include Multiflow
+
+  stateflow do
+    create_scopes false
+    initial :red
+
+    state :red, :green
+
+    event :change do
+      transitions :from => :red, :to => :green
+    end
+  end
+end
+
+class ActiveRecordStateColumnSetRobot < ActiveRecord::Base
+  include Multiflow
+
+  stateflow do
+    state_column :status
+    initial :red
+
+    state :red, :green
+
+    event :change do
+      transitions :from => :red, :to => :green
+    end
+  end
+end
+
+describe Multiflow::Persistence::ActiveRecord do
+  before(:all) { TestMigration.up }
+  after(:all) { TestMigration.down }
+  after { ActiveRecordRobot.delete_all }
+
+  let(:robot) { ActiveRecordRobot.new }
+
+  describe "includes" do
+    it "should include current_state" do
+      robot.respond_to?(:current_state).should be_true
+    end
+
+    it "should include current_state=" do
+      robot.respond_to?(:set_current_state).should be_true
+    end
+
+    it "should include save_to_persistence" do
+      robot.respond_to?(:save_to_persistence).should be_true
+    end
+
+    it "should include load_from_persistence" do
+      robot.respond_to?(:load_from_persistence).should be_true
+    end
+  end
+
+  describe "bang method" do
+    before do
+      @robot = robot
+      @robot.state = "red"
+    end
+
+    it "should call the set_current_state with save being true" do
+      @robot.should_receive(:set_current_state).with(@robot.machine_state.states[:green], {:save=>true})
+      @robot.change!
+    end
+
+    it "should call the setter method for the state column" do
+      @robot.should_receive(:state=).with("green")
+      @robot.change!
+    end
+
+    it "should call save after setting the state column" do
+      @robot.should_receive(:save!)
+      @robot.change!
+    end
+
+    it "should save the record" do
+      @robot.new_record?.should be_true
+      @robot.change!
+      @robot.new_record?.should be_false
+      @robot.reload.state.should == "green"
+    end
+  end
+
+    describe "non bang method" do
+    before do
+      @robot = robot
+      @robot.state = "red"
+    end
+
+    it "should call the set_current_state with save being false" do
+      @robot.should_receive(:set_current_state).with(@robot.machine_state.states[:green], {:save=>false})
+      @robot.change
+    end
+
+    it "should call the setter method for the state column" do
+      @robot.should_receive(:state=).with("green")
+      @robot.change
+    end
+
+    it "should call save after setting the state column" do
+      @robot.should_not_receive(:save)
+      @robot.change
+    end
+
+    it "should not save the record" do
+      @robot.new_record?.should be_true
+      @robot.change
+      @robot.new_record?.should be_true
+      @robot.state.should == "green"
+    end
+  end
+
+  it "Make sure stateflow saves the initial state if no state is set" do
+    @robot3 = robot
+
+    @robot3.save
+    @robot3.reload
+
+    @robot3.state.should == "red"
+  end
+
+  describe "load from persistence" do
+    before do
+      @robot = robot
+      @robot.state = "green"
+      @robot.name = "Bottie"
+      @robot.save
+    end
+
+    it "should call the load_from_persistence method" do
+     @robot.reload
+     @robot.should_receive(:load_from_persistence)
+
+     @robot.current_state
+    end
+  end
+
+  describe "scopes" do
+    it "should be added for each state" do
+      ActiveRecordRobot.should respond_to(:red)
+      ActiveRecordRobot.should respond_to(:green)
+    end
+    it "should be added for each state when the state column is not 'state'" do
+      ActiveRecordStateColumnSetRobot.should respond_to(:red)
+      ActiveRecordStateColumnSetRobot.should respond_to(:green)
+    end
+
+    it "should not be added for each state" do
+      ActiveRecordNoScopeRobot.should_not respond_to(:red)
+      ActiveRecordNoScopeRobot.should_not respond_to(:green)
+    end
+
+    it "should behave like Mongoid scopes" do
+      2.times { ActiveRecordRobot.create(:state => "red") }
+      3.times { ActiveRecordRobot.create(:state => "green") }
+      ActiveRecordRobot.red.count.should == 2
+      ActiveRecordRobot.green.count.should == 3
+    end
+  end
+end
+

data/spec/spec_helper.rb

@@ -0,0 +1,4 @@
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+
+require 'multiflow'

data/spec/stateflow_spec.rb

@@ -0,0 +1,347 @@
+require 'spec_helper'
+
+Multiflow.persistence = :none
+
+class Robot
+  include Multiflow
+
+  stateflow do
+    initial :green
+
+    state :green, :yellow, :red
+
+    event :change_color do
+      transitions :from => :green, :to => :yellow
+      transitions :from => :yellow, :to => :red
+      transitions :from => :red, :to => :green
+    end
+  end
+end
+
+class Car
+  include Multiflow
+
+  stateflow do
+    initial :parked
+
+    state :parked do
+      enter do
+        "Entering parked"
+      end
+
+      exit do
+        "Exiting parked"
+      end
+    end
+
+    state :driving do
+      enter do
+        "Entering parked"
+      end
+    end
+
+    event :drive do
+      transitions :from => :parked, :to => :driving
+    end
+
+    event :park do
+      transitions :from => :driving, :to => :parked
+    end
+  end
+end
+
+class Bob
+  include Multiflow
+
+  stateflow do
+    state :yellow, :red, :purple
+
+    event :change_hair_color do
+      transitions :from => :purple, :to => :yellow
+      transitions :from => :yellow, :to => :red
+      transitions :from => :red, :to => :purple
+    end
+  end
+end
+
+class Dater
+  include Multiflow
+
+  stateflow do
+    state :single, :dating, :married
+
+    event :take_out do
+      transitions :from => :single, :to => :dating
+    end
+
+    event :gift do
+      transitions :from => :dating, :to => [:single, :married], :decide => :girls_mood?
+    end
+
+    event :blank_decision do
+      transitions :from => :single, :to => [:single, :married], :decide => :girls_mood?
+    end
+
+    event :fail do
+      transitions :from => :dating, :to => [:single, :married]
+    end
+  end
+
+  def girls_mood?
+  end
+end
+
+class Priority
+  include Multiflow
+
+  stateflow do
+    initial :medium
+    state :low, :medium, :high
+
+    event :low do
+      transitions :from => any, :to => :low
+    end
+
+    event :medium do
+      transitions :from => any, :to => :medium
+    end
+
+    event :high do
+      transitions :from => any, :to => :high
+    end
+  end
+end
+
+class Stater
+  include Multiflow
+
+  stateflow do
+    initial :bill
+
+    state :bob, :bill
+
+    event :lolcats do
+      transitions :from => :bill, :to => :bob
+    end
+  end
+end
+
+describe Multiflow do
+  describe "class methods" do
+    it "should respond to stateflow block to setup the intial stateflow" do
+      Robot.should respond_to(:stateflow)
+    end
+
+    it "should respond to the machine attr accessor" do
+      Robot.should respond_to(:machine_state)
+    end
+
+    it "should return all active persistence layers" do
+      Set[*Multiflow::Persistence.active.should] == Set[:active_record, :mongo_mapper, :mongoid, :none]
+    end
+  end
+
+  describe "instance methods" do
+    before(:each) do
+      @r = Robot.new
+    end
+
+    it "should respond to current state" do
+      @r.should respond_to(:current_state)
+    end
+
+    it "should respond to the current state setter" do
+      @r.should respond_to(:set_current_state)
+    end
+
+    it "should respond to the current machine" do
+      @r.should respond_to(:machine_state)
+    end
+
+    it "should respond to load from persistence" do
+      @r.should respond_to(:load_from_persistence)
+    end
+
+    it "should respond to save to persistence" do
+      @r.should respond_to(:save_to_persistence)
+    end
+  end
+
+  describe "initial state" do
+    it "should set the initial state" do
+      robot = Robot.new
+      robot.current_state.name.should == :green
+    end
+
+    it "should return true for green?" do
+      robot = Robot.new
+      robot.green?.should be_true
+    end
+
+    it "should return false for yellow?" do
+      robot = Robot.new
+      robot.yellow?.should be_false
+    end
+
+    it "should return false for red?" do
+      robot = Robot.new
+      robot.red?.should be_false
+    end
+
+    it "should set the initial state to the first state set" do
+      bob = Bob.new
+      bob.current_state.name.should == :yellow
+      bob.yellow?.should be_true
+    end
+  end
+
+  it "robot class should contain red, yellow and green states" do
+    robot = Robot.new
+    robot.machine_state.states.keys.should include(:red, :yellow, :green)
+  end
+
+  describe "firing events" do
+    let(:robot) { Robot.new }
+    let(:event) { :change_color }
+    subject { robot }
+
+    it "should raise an exception if the event does not exist" do
+      lambda { robot.send(:fire_event, robot.machine_state, :fake) }.should raise_error(Multiflow::NoEventFound)
+    end
+
+    shared_examples_for "an entity supporting state changes" do
+      context "when firing" do
+        after(:each) { subject.send(event_method) }
+        it "should call the fire method on event" do
+          subject.machine_state.events[event].should_receive(:fire)
+        end
+
+        it "should call the fire_event method" do
+          subject.should_receive(:fire_event).with(subject.machine_state, event, {:save=>persisted})
+        end
+      end
+
+      it "should update the current state" do
+        subject.current_state.name.should == :green
+        subject.send(event_method)
+        subject.current_state.name.should == :yellow
+      end
+    end
+
+    describe "bang event" do
+      let(:event_method) { :change_color! }
+      let(:persisted)    { true }
+      it_should_behave_like "an entity supporting state changes"
+    end
+
+    describe "non-bang event" do
+      let(:event_method) { :change_color }
+      let(:persisted)    { false }
+      it_should_behave_like "an entity supporting state changes"
+    end
+
+    describe "before filters" do
+      before(:each) do
+        @car = Car.new
+      end
+
+      it "should call the exit state before filter on the exiting old state" do
+        @car.machine_state.states[:parked].should_receive(:execute_action).with(:exit, @car)
+        @car.drive!
+      end
+
+      it "should call the enter state before filter on the entering new state" do
+        @car.machine_state.states[:driving].should_receive(:execute_action).with(:enter, @car)
+        @car.drive!
+      end
+    end
+  end
+
+  describe "persistence" do
+    it "should attempt to persist the new state and the name should be a string" do
+      robot = Robot.new
+      robot.should_receive(:save_to_persistence).with(robot.machine_state, "yellow", {:save=>true})
+      robot.change_color!
+    end
+
+    it "should attempt to read the initial state from the persistence" do
+      robot = Robot.new
+
+      def robot.load_from_persistence(machine)
+        :red
+      end
+
+      robot.current_state.name.should == :red
+    end
+  end
+
+  describe "dynamic to transitions" do
+    it "should raise an error without any decide argument" do
+      date = Dater.new
+
+      def date.load_from_persistence(machine)
+        :dating
+      end
+
+      lambda { date.fail! }.should raise_error(Multiflow::IncorrectTransition)
+    end
+
+    it "should raise an error if the decision method does not return a valid state" do
+      date = Dater.new
+
+      def date.girls_mood?
+        :lol
+      end
+
+      lambda { date.blank_decision! }.should raise_error(Multiflow::NoStateFound, "Decision did not return a state that was set in the 'to' argument")
+    end
+
+    it "should raise an error if the decision method returns blank/nil" do
+      date = Dater.new
+
+      def date.girls_mood?
+      end
+
+      lambda { date.blank_decision! }.should raise_error(Multiflow::NoStateFound, "Decision did not return a state that was set in the 'to' argument")
+    end
+
+    it "should calculate the decide block or method and transition to the correct state" do
+      date = Dater.new
+
+      def date.load_from_persistence(machine)
+        :dating
+      end
+
+      date.current_state.name.should == :dating
+
+      def date.girls_mood?
+        :single
+      end
+
+      date.gift!
+
+      date.current_state.name.should == :single
+    end
+  end
+
+  describe "transitions from any" do
+    it "should properly change state" do
+      priority = Priority.new
+      priority.low!
+      priority.should be_low
+      priority.medium!
+      priority.should be_medium
+      priority.high!
+      priority.should be_high
+    end
+  end
+
+  describe 'sub-classes of Multiflow\'d classes' do
+    subject { Class.new(Stater) }
+
+    it 'shouldn\'t raise an exception' do
+      expect { subject.new.lolcats! }.not_to raise_exception
+    end
+  end
+
+end