golem_statemachine 0.9

data/lib/golem/dsl/transition_def.rb

@@ -0,0 +1,51 @@
+require 'golem/model/condition'
+require 'golem/model/callback'
+
+module Golem
+  module DSL
+    class TransitionDef
+      def initialize(machine, event, from_state, options = {}, &block)
+        @machine = machine
+        @event = event
+        @from = from_state
+        
+        if options[:to].blank? || options[:to] == :self
+          @to = options[:to] = @state
+        else
+          @to = @machine.get_or_define_state(options[:to])
+        end
+
+        callbacks = {}
+        callbacks[:on_transition] = options[:action] if options[:action]
+
+        @transition = Golem::Model::Transition.new(@from, @to || @from, options[:guards], callbacks)
+
+        instance_eval(&block) if block
+
+        @from.transitions_on_event[@event] ||= []
+        @from.transitions_on_event[@event] << @transition
+      end
+
+      def guard(callback_or_options = {}, guard_options = {}, &block)
+        if callback_or_options.kind_of? Hash
+          callback = block
+          guard_options = callback_or_options
+        else
+          callback = callback_or_options
+        end
+        
+        @transition.guards << Golem::Model::Condition.new(callback, guard_options)
+      end
+
+      def action(callback = nil, &block)
+        #if @transition.callbacks[:on_transition]
+        #  puts "WARNING: Overriding event action for #{@transition.to_s.inspect}."
+        #end
+
+        callback = block unless callback
+
+        @transition.callbacks[:on_transition] = Golem::Model::Callback.new(callback)
+      end
+    end
+  end
+end

data/lib/golem/model/callback.rb

@@ -0,0 +1,32 @@
+module Golem
+  module Model
+    class Callback
+      attr_accessor :callback
+
+      def initialize(callback, options = {})
+        @callback = callback
+      end
+
+      def call(obj, *args)
+        case @callback
+        when Proc
+          if @callback.arity.abs > 1
+            @callback.call(obj, *args)
+          else
+            @callback.call(obj)
+          end
+        else
+          if obj.method(@callback).arity.abs > 0
+            obj.send(@callback, *args)
+          else
+            obj.send(@callback)
+          end
+        end
+      end
+
+      def to_s
+        "#{@callback.inspect}"
+      end
+    end
+  end
+end

data/lib/golem/model/condition.rb

@@ -0,0 +1,12 @@
+module Golem
+  module Model
+    class Condition < Golem::Model::Callback
+      attr_accessor :failure_message
+
+      def initialize(callback, options = {})
+        @callback = callback
+        @failure_message = options[:failure_message]
+      end
+    end
+  end
+end

data/lib/golem/model/event.rb

@@ -0,0 +1,12 @@
+module Golem
+  module Model
+    class Event
+      attr_reader :name
+      attr_reader :callbacks
+
+      def initialize(name)
+        @name = name
+      end
+    end
+  end
+end

data/lib/golem/model/state.rb

@@ -0,0 +1,26 @@
+require 'golem/util/element_collection'
+
+module Golem
+  module Model
+    class State
+      attr_reader :name
+      attr_reader :callbacks
+      attr_reader :transitions_on_event
+
+      def initialize(name)
+        name = name.to_sym unless name.is_a?(Symbol)
+        @name = name
+        @transitions_on_event = Golem::Util::ElementCollection.new
+        @callbacks = {}
+      end
+
+      def to_s
+        name.to_s
+      end
+
+      def to_sym
+        name.to_sym
+      end
+    end
+  end
+end

data/lib/golem/model/state_machine.rb

@@ -0,0 +1,224 @@
+require 'golem/model/event'
+require 'golem/model/state'
+require 'golem/model/transition'
+require 'golem/util/element_collection'
+
+module Golem
+
+  module Model
+
+    class StateMachine
+      attr_accessor :name
+      attr_accessor :state_attribute
+      attr_reader :states
+      attr_reader :events
+      attr_accessor :transition_errors
+
+      # Callback executed on every successful transition.
+      attr_accessor :on_all_transitions
+
+      # Callback executed on every successful event.
+      attr_accessor :on_all_events
+
+      def initialize(name)
+        @name = name
+        @states = Golem::Util::ElementCollection.new(Golem::Model::State)
+        @events = Golem::Util::ElementCollection.new(Golem::Model::Event)
+        @transition_errors = []
+        @throw_exceptions = false
+      end
+
+      def initial_state
+        @initial_state
+      end
+
+      def initial_state=(state)
+        # for the sake of readability in debugging, we store initial state by name rather than by reference to a State object
+        @initial_state = state.name
+      end
+
+      def all_states
+        @states
+      end
+
+      def all_events
+        @events
+      end
+
+      def get_current_state_of(obj)
+        obj.send(state_attribute)
+      end
+
+      def set_current_state_of(obj, state)
+        obj.send("#{state_attribute}=".to_sym, state)
+      end
+
+      def init(obj, *args)
+        # set the initial state
+        set_current_state_of(obj, initial_state)
+
+        # call the on_entry callback for the initial state (if defined)
+        init_state = states[get_current_state_of(obj)]
+        init_state.callbacks[:on_enter].call(obj, *args) if init_state && init_state.callbacks[:on_enter]
+      end
+
+      def fire_event_with_exceptions(obj, event, *args)
+        @throw_exceptions = true
+        fire_event(obj, event, *args)
+      end
+
+      def fire_event_without_exceptions(obj, event, *args)
+        @throw_exceptions = false
+        fire_event(obj, event, *args)
+      end
+
+      def fire_event(obj, event, *args)
+        @transition_errors = []
+        transition = determine_transition_on_event(obj, event, *args)
+        
+        on_all_events.call(obj, event, args) if on_all_events
+
+        if transition
+          before_state = states[get_current_state_of(obj)]
+          before_state.callbacks[:on_exit].call(obj, *args) if before_state.callbacks[:on_exit]
+          
+          set_current_state_of(obj, transition.to.name)
+          transition.callbacks[:on_transition].call(obj, *args) if transition.callbacks[:on_transition]
+          on_all_transitions.call(obj, event, transition, *args) if on_all_transitions
+
+          after_state = states[get_current_state_of(obj)]
+          after_state.callbacks[:on_enter].call(obj, *args) if after_state.callbacks[:on_enter]
+          
+          save_result = true
+          if @throw_exceptions
+            save_result = obj.save! if obj.respond_to?(:save!)
+          else
+            save_result = obj.save if obj.respond_to?(:save)
+          end
+          return save_result
+        else
+          return false
+        end
+      end
+
+      def determine_transition_on_event(obj, event, *args)
+        event = @events[event] unless event.is_a?(Golem::Model::Event)
+
+        from_state = states[get_current_state_of(obj)]
+        possible_transitions = from_state.transitions_on_event[event.name]
+
+        selected_transition = determine_transition(possible_transitions, obj, *args)
+
+        if selected_transition.nil?
+          if @cannot_transition_because.blank?
+            msg = "#{event.name.to_s.inspect} is not a valid action for #{obj} because no outgoing transitions are available when #{name.blank? ? "the state" : "#{name} "} is #{from_state}."
+            msg << "\n\tPossible transitions are: \n\t\t#{possible_transitions.collect.collect{|t| t.to_s}.join("\n\t\t")}" unless possible_transitions.blank?
+          elsif @cannot_transition_because.length == 1
+            msg = "#{event.name.to_s.inspect} is not a valid action for #{obj} because #{@cannot_transition_because.first}."
+          else
+            msg = "#{event.name.to_s.inspect} is not a valid action for #{obj} because #{@cannot_transition_because.uniq.join(" and ")}"
+          end
+
+          if @throw_exceptions
+            raise Golem::ImpossibleEvent.new(msg, event, obj, @cannot_transition_because)
+          else
+            obj.transition_errors << msg
+          end
+        end
+
+        return selected_transition
+      end
+
+      def get_or_define_state(state)
+        if states[state]
+          return states[state]
+        else
+          case state
+          when Golem::Model::State
+            return states[state] = state
+          when String, Symbol
+            return states[state] = Golem::Model::State.new(state)
+          else
+            raise ArgumentError, "State must be a Golem::Model::State, String, or Symbol but is a #{state.class}"
+          end
+        end
+      end
+
+      def get_or_define_event(event)
+        if events[event]
+          return events[event]
+        else
+          case event
+          when Golem::Model::Event
+            return events[event] = event
+          when String, Symbol
+            return events[event] = Golem::Model::Event.new(event)
+          else
+            raise ArgumentError, "Event must be a Golem::Model::Event, String, or Symbol but is a #{event.class}"
+          end
+        end
+      end
+
+#      def get_or_create_state(name, options = {})
+#        @states[name] || define_state(name, options)
+#      end
+#
+#      def define_state(name, options = {})
+#
+#        s.set_callback(:on_enter, options[:enter]) if options[:enter]
+#        s.set_callback(:on_exit, options[:exit]) if options[:exit]
+#        # TODO: implement :do callback as an "Activity" (Thread/subrocess?)
+#        states[name] = s
+#        return s
+#      end
+#
+#      def get_or_define_event(name, options = {})
+#        @events[name] || define_event(name, options)
+#      end
+#
+#      def define_event(name, options = {}, &block)
+#        e = Event.new(name)
+#        e.instance_eval(&block) if block
+#
+#        model.class_eval do
+#          define_method("#{name}!") do |*args|
+#            model.transaction do
+#              e.fire(args)
+#            end
+#          end
+#        end
+#
+#        @events << e
+#        return e
+#      end
+
+      private
+      
+      def determine_transition(possible_transitions, obj, *args)
+        return nil if possible_transitions.blank?
+
+        @cannot_transition_because = []
+        
+        possible_transitions.each do |transition|
+          guard_failed = false
+          unless transition.guards.empty?
+            transition.guards.each do |guard| # all guards must evaluate to true
+              unless guard.call(obj, *args)
+                @cannot_transition_because << (guard.failure_message || "#{guard} is false")
+                guard_failed = true
+                break
+              end
+            end
+          end
+
+          next if guard_failed
+
+          return transition
+        end
+
+        return nil
+      end
+      
+    end
+  end
+end

data/lib/golem/model/transition.rb

@@ -0,0 +1,37 @@
+# To change this template, choose Tools | Templates
+# and open the template in the editor.
+
+module Golem
+  module Model
+    class Transition
+      attr_reader :from
+      attr_reader :to
+      attr_accessor :guards
+      attr_accessor :callbacks
+
+      def initialize(from, to, guards = [], callbacks = {})
+        @from = from
+        @to = to
+        
+        raise ArgumentError, "'guards' must be an Enumerable collection of Golem::Model::Conditions but is #{guards.inspect}" unless
+          guards.blank? || (guards.kind_of?(Enumerable) && guards.all?{|g| g.kind_of?(Golem::Model::Condition)})
+
+        @guards = guards
+        
+        raise ArgumentError, "'callbacks' must be a Hash of Golem::Model::Callbacks but is #{callbacks.inspect}" unless
+          callbacks.blank? || (callbacks.kind_of?(Hash) && callbacks.all?{|k, c| c.kind_of?(Golem::Model::Callback)})
+
+        # only the :on_transition callback is currently implemented, but using a Hash of callbacks here leaves open
+        # the possibility of other callbacks (e.g. :on_start, :on_finish, etc.)
+        @callbacks = callbacks
+      end
+
+      def to_s
+        s ="Transition from #{from} to #{to}"
+        s << " [#{guards.collect{|g| g.to_s}.join(" and ")}]" unless guards.empty?
+        s << " / #{callbacks.collect{|k,v| v.to_s}.join(",")}" unless callbacks.blank? || callbacks.values.all?{|v| v.blank?}
+        return s
+      end
+    end
+  end
+end

data/lib/golem/util/element_collection.rb

@@ -0,0 +1,33 @@
+module Golem
+  module Util
+    class ElementCollection
+      include Enumerable
+
+      def initialize(restricted_to_type = nil)
+        @collection = {}
+        @restricted_to_type = restricted_to_type
+      end
+
+      def [](key)
+        return nil if key.nil?
+        key = key.name if key.respond_to?(:name)
+        @collection[key.to_sym]
+      end
+
+      def []=(key, value)
+        key = key.name if key.respond_to?(:name)
+        raise ArgumentError, "Value must be a #{@restricted_to_type.name.inspect} but is a #{value.class.name.inspect}!" if
+          @restricted_to_type && !value.kind_of?(@restricted_to_type)
+        @collection[key.to_sym] = value
+      end
+
+      def each
+        @collection.values.each{|v| yield v}
+      end
+
+      def values
+        @collection.values
+      end
+    end
+  end
+end

data/tasks/golem_statemachine_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :golem_statemachine do
+#   # Task goes here
+# end

data/test/active_record_test.rb

@@ -0,0 +1,189 @@
+require 'test_helper'
+
+require 'rubygems'
+
+
+begin
+  require 'sqlite3'
+rescue
+  gem 'sqlite3-ruby'
+  require 'sqlite3'
+end
+
+require 'activerecord'
+
+require 'ruby-debug'
+
+class ActiveRecordTest < Test::Unit::TestCase
+
+  def setup
+    eval %{
+      class Foo < ActiveRecord::Base
+        include Golem
+      end
+    }
+
+    File.delete('test.db') if File.exists?('test.db')
+    
+    ActiveRecord::Base.establish_connection(
+      :adapter => 'sqlite3',
+      :database => 'test.db'
+    )
+
+    tmp = $stdout
+    $stdout = StringIO.new
+    ActiveRecord::Schema.define do
+      create_table :foos do |t|
+        t.column :state, :string, :null => true
+        t.column :alpha_state, :string, :null => true
+        t.column :status, :string, :null => true
+      end
+    end
+    $stdout = tmp
+  end
+
+  def teardown
+    self.class.send(:remove_const, :Foo)
+  end
+
+  def test_restore_state
+    foo = Foo.create(
+      :state => 'b',
+      :alpha_state => 'c',
+      :status => 'd'
+    )
+
+    Foo.instance_eval do
+      define_statemachine do
+        initial_state :a
+        state :a
+        state :b
+        state :c
+        state :d
+      end
+
+      define_statemachine(:alpha) do
+        initial_state :a
+        state :a
+        state :b
+        state :c
+        state :d
+      end
+
+      define_statemachine(:beta) do
+        state_attribute(:status)
+        initial_state :a
+        state :a
+        state :b
+        state :c
+        state :d
+      end
+    end
+
+    foo = Foo.find(foo.id)
+
+    assert_equal :b, foo.state
+    assert_equal :c, foo.alpha_state
+    assert_equal :d, foo.status
+
+    # check that initial state works too
+    foo = Foo.create
+
+    foo = Foo.find(foo.id)
+
+    assert_equal :a, foo.state
+    assert_equal :a, foo.alpha_state
+    assert_equal :a, foo.status
+  end
+
+  def test_save_state
+    Foo.instance_eval do
+      define_statemachine do
+        initial_state :a
+        state :a do
+          on :go, :to => :b
+        end
+        state :b
+        state :c
+        state :d
+      end
+
+      define_statemachine(:alpha) do
+        initial_state :a
+        state :a do
+          on :go, :to => :c
+        end
+        state :b
+        state :c
+        state :d
+      end
+
+      define_statemachine(:beta) do
+        state_attribute(:status)
+        initial_state :a
+        state :a do
+          on :go, :to => :d
+        end
+        state :b
+        state :c
+        state :d
+      end
+    end
+
+    foo = Foo.create
+
+    assert_equal :a, foo.state
+    assert_equal :a, foo.alpha_state
+    assert_equal :a, foo.status
+
+    foo.go
+    
+    assert_equal :b, foo.state
+    assert_equal :c, foo.alpha_state
+    assert_equal :d, foo.status
+
+    foo = Foo.find(foo.id)
+
+    assert_equal :b, foo.state
+    assert_equal :c, foo.alpha_state
+    assert_equal :d, foo.status
+  end
+
+
+  def test_fire_entry_action_on_initial_state
+    Foo.instance_eval do
+      define_statemachine do
+        initial_state :a
+        state :a do
+          enter do |r|
+            throw :it_worked!
+          end
+          on :go, :to => :b
+        end
+        state :b
+      end
+
+      define_statemachine(:alpha) do
+        initial_state :a
+        state :a do
+          on :go, :to => :c
+        end
+        state :b
+        state :c
+        state :d
+      end
+    end
+
+    assert_throws :it_worked! do
+      foo = Foo.create
+    end
+  end
+
+
+  def test_transaction_around_fire_event
+    #TODO: check that transaction around fire_event is respected (i.e. changes not persisted when an execption is
+    #      raised inside an event firing)
+  end
+
+end
+