golem_statemachine 0.9

data/init.rb

@@ -0,0 +1,5 @@
+my_dir = File.expand_path(File.dirname(__FILE__))+'/lib'
+ActiveSupport::Dependencies.load_once_paths.delete my_dir unless RAILS_ENV == 'production'
+
+$: << my_dir
+require 'golem'

data/install.rb

@@ -0,0 +1 @@
+# Install hook code here

data/lib/golem.rb

@@ -0,0 +1,207 @@
+require 'activesupport'
+
+require 'golem/dsl/state_machine_def'
+
+module Golem
+  def self.included(mod)
+    mod.extend Golem::ClassMethods
+
+    # Override the initialize method in the object we're imbuing with statemachine
+    # functionality so that we can do statemachine initialization when the object
+    # is instantiated.
+    mod.class_eval do
+      alias_method :_initialize, :initialize
+      def initialize(*args)
+        # call the original initialize
+        _initialize(*args)
+        
+        if respond_to?(:statemachines)
+          self.statemachines.each{|name, sm| sm.init(self, *args)}
+        end
+      end
+    end
+  end
+
+  module ClassMethods
+    def define_statemachine(statemachine_name = nil, options = {}, &block)
+      default_statemachine_name = :statemachine
+      
+      class_inheritable_hash(:statemachines) unless respond_to?(:statemachines)
+      self.statemachines ||= {}
+      
+      if statemachines.has_key?(statemachine_name || default_statemachine_name)
+        if statemachine_name == default_statemachine_name
+          raise ArgumentError, "If you are declaring more than one statemachine within the same class, you must give each statemachine a unique name (i.e. define_statemachine(name) do ... end)."
+        else
+          raise ArgumentError, "Cannot declare a statemachine under #{(statemachine_name || default_statemachine_name).inspect} because this statemachine name is already taken."
+        end
+      end
+
+      statemachine_def = Golem::DSL::StateMachineDef.new(self, statemachine_name, &block)
+      
+      statemachine = statemachine_def.machine
+
+      raise Golem::DefinitionSyntaxError, "No initial_state defined for statemachine #{statemachine}!" if statemachine.initial_state.blank?
+
+      self.statemachines[statemachine_name || default_statemachine_name] = statemachine
+      class_eval do
+        define_method(statemachine_name || default_statemachine_name) do
+          statemachines[statemachine_name || default_statemachine_name]
+        end
+      end
+
+      state_attribute = statemachine_def.state_attribute
+
+      if state_attribute.blank?
+        if statemachine_name.nil?
+          state_attribute = :state
+        else
+          state_attribute = "#{statemachine_name}_state".to_sym
+        end
+      end
+
+      statemachine.state_attribute = state_attribute
+
+      # state reader
+      define_method("#{state_attribute}".to_sym) do
+        case
+        when state_attribute.respond_to?(:call)
+          state = state_attribute.call(self)
+        when Object.const_defined?('ActiveRecord') && self.kind_of?(ActiveRecord::Base)
+          state = self[state_attribute.to_s] && self[state_attribute.to_s].to_sym
+        else
+          state = self.instance_variable_get("@#{state_attribute}")
+        end
+        
+        state ||= statemachine.initial_state
+        state   = state.to_sym if state.is_a?(String)
+
+        raise InvalidStateError, "#{self} is in an unrecognized state (#{state.inspect})" unless statemachine.states[state]
+
+        state   = statemachine.states[state].name
+        
+        return state
+      end
+
+      # state writer
+      define_method("#{state_attribute}=".to_sym) do |new_state|
+        new_state = new_state.name if new_state.respond_to?(:name)
+        new_state = new_state.to_sym
+        raise ArgumentError, "#{new_state.inspect} is not a valid state for #{statemachine}!" unless statemachine.states[new_state]
+        
+        case
+        when state_attribute.respond_to?(:call)
+          state_attribute.call(self, new_state)
+        when Object.const_defined?('ActiveRecord') && self.kind_of?(ActiveRecord::Base)
+          self[state_attribute.to_s] = new_state.to_s # store as String rather than Symbol to prevent serialization weirdness
+        else
+          self.instance_variable_set("@#{state_attribute}", new_state)
+        end
+      end
+
+      validate :check_for_transition_errors if respond_to? :validate
+
+      define_method(:transition_errors) do
+        @transition_errors ||= []
+      end
+
+      define_method(:check_for_transition_errors) do
+        if transition_errors && !transition_errors.empty?
+          transition_errors.each do |err|
+            errors.add_to_base(err)
+          end
+        end
+      end
+
+
+      statemachine.events.each do |event|
+        self.class_eval do
+          
+          # For every event defined in each statemachine we define a regular
+          # (non-exception-raising) method and bang! (exception-raising).
+          # This allows for triggering the event by calling the appropriate
+          # event-named method on the object.
+          [event.name,"#{event.name}!"].each do |meth|
+            define_method(meth) do |*args|
+              fire_proc = lambda do
+                impossible = {}
+                results = self.statemachines.collect do |name, sm|
+                  begin
+                    if meth =~ /!$/
+                      sm.fire_event_with_exceptions(self, event, *args)
+                    else
+                      sm.fire_event_without_exceptions(self, event, *args)
+                    end
+                  rescue Golem::ImpossibleEvent => e
+                    impossible[sm] = e
+                  end
+                end
+                if impossible.size == self.statemachines.size
+                  # all statemachines raised Golem::ImpossibleEvent
+                  message = impossible.values.collect{|e| e.message}.uniq.join("\n")
+                  events = impossible.values.collect{|e| e.event}.uniq
+                  events = events[0] if events.size <= 1
+                  objects = impossible.values.collect{|e| e.object}.uniq
+                  objects = objects[0] if objects.size <= 1
+                  reasons = impossible.values.collect{|e| e.reasons}.flatten.uniq
+                  reasons = reasons[0] if reasons.size <= 1
+                  raise Golem::ImpossibleEvent.new(message, events, objects, reasons)
+                end
+                results.all?{|result| result == true}
+              end
+
+              if self.class.respond_to?(:transaction)
+                 # Wrap event call inside a transaction, if supported (i.e. for ActiveRecord)
+                self.class.transaction(&fire_proc)
+              else
+                fire_proc.call
+              end
+            end
+          end
+
+          define_method("determine_#{"#{statemachine_name}_" if statemachine_name}state_after_#{event.name}") do |*args|
+            transition = nil
+            if self.class.respond_to?(:transaction)
+              self.class.transaction do
+                # TODO: maybe better to use fire_event + transaction rollback to simulate event firing?
+                transition = statemachine.determine_transition_on_event(self, event, *args)
+              end
+            else
+              transition = statemachine.determine_transition_on_event(self, event, *args)
+            end
+
+            transition ? transition.to.name : nil
+          end
+        end
+      end
+    end
+  end
+
+  class ImpossibleEvent < StandardError
+    attr_reader :event, :object, :reasons
+    def initialize(message, event = nil, object = nil, reasons = nil)
+      @event = event
+      @object = object
+      @reasons = reasons
+      super(message)
+    end
+
+    def human_explanation
+      event = [@event] unless @event.is_a?(Array)
+      object = [@object] unless @object.is_a?(Array)
+      "'#{event.collect{|ev|ev.name.to_s.humanize.upcase}.join("/")}' for #{object.collect{|ob|ob.to_s}.join("/")} failed"
+    end
+
+    def human_reasons
+      reasons = [@reasons] unless @reasons.is_a?(Array)
+      reasons
+    end
+  end
+
+  class DefinitionSyntaxError < StandardError
+  end
+
+  class InvalidStateError < StandardError
+  end
+  
+end

data/lib/golem/dsl/decision_def.rb

@@ -0,0 +1,38 @@
+require 'golem/model/state'
+require 'golem/model/transition'
+
+module Golem
+  module DSL
+    class DecisionDef
+      def initialize(machine, state, event)
+        @machine = machine
+        @state = state
+        @event = event
+      end
+
+      def transition(options, &block)
+        if options[:to]
+          to = @machine.states[options[:to]] ||= Golem::Model::State.new(options[:to])
+        else
+          # self-transition
+          to = @state
+        end
+
+        if options[:guard] || options[:if]
+           options[:guard] = Golem::Model::Callback.new(options[:guard] || options[:if]) # :guard and :if mean the same thing
+        end
+
+        if block || options[:action]
+           options[:action] = Golem::Model::Callback.new(options[:action] || block)
+        end
+        
+        @state.transitions_on_event[@event.name] ||= []
+        @state.transitions_on_event[@event.name] << Golem::Model::Transition.new(@state, to, options)
+      end
+
+      def method_missing?
+        raise SyntaxError, "Only 'transition' declarations can be placed in a state's decision block."
+      end
+    end
+  end
+end

data/lib/golem/dsl/event_def.rb

@@ -0,0 +1,89 @@
+require 'golem/dsl/transition_def'
+
+module Golem
+  module DSL
+    class EventDef
+      def initialize(machine, on_state, event_name, options, &block)
+        @machine = machine
+        @state = on_state
+        @event = @machine.get_or_define_event(event_name)
+
+        if options[:to]
+          @to = @machine.get_or_define_state(options[:to])
+        end
+
+        @guards = []
+
+        guard = options[:if] || options[:guard]
+        if guard
+          if guard.kind_of?(Golem::Model::Condition)
+            @guards << guard
+          else
+            @guards << Golem::Model::Condition.new(guard, options[:guard_options] || {})
+          end
+        end
+
+        action = options[:action] || options[:on_transition]
+        @action = Golem::Model::Callback.new(action) if action
+
+        
+        instance_eval(&block) if block_given?
+
+        if @state.transitions_on_event[@event].blank?
+          transition :to => (@to || @state), :guards => @guards, :action => @action
+        end
+      end
+
+      def transition(options = {}, &block)
+        if options[:to] == :self
+          to = @state
+        elsif options[:to]
+          to = @machine.get_or_define_state(options[:to])
+        else
+          to = @to
+        end
+
+        options[:to] = to
+
+        guard = options[:if] || options[:guard]
+        if guard
+          if guard.kind_of?(Golem::Model::Condition)
+            guards = @guards + [guard]
+          else
+            guards = @guards + [Golem::Model::Condition.new(guard)]
+          end
+        end
+
+        options[:guards] = guards || @guards.dup
+        
+        action = options[:action] || options[:on_transition]
+        if action
+          options[:action] = Golem::Model::Callback.new(action) unless action.kind_of?(Golem::Model::Callback)
+        else
+          options[:action] = @action
+        end
+
+        TransitionDef.new(@machine, @event, @state, options.dup, &block)
+      end
+
+      def guard(callback_or_options = {}, guard_options = {}, &block)
+        # FIXME: are guard_options ever actually used?
+        if callback_or_options.kind_of? Hash
+          callback = block
+          guard_options = callback_or_options
+        else
+          callback = callback_or_options
+        end
+
+        @guards << Golem::Model::Condition.new(callback, guard_options)
+      end
+
+      def action(callback = nil, &block)
+        callback = block unless callback
+
+        @action = Golem::Model::Callback.new(callback)
+      end
+
+    end
+  end
+end

data/lib/golem/dsl/state_def.rb

@@ -0,0 +1,34 @@
+require 'golem/model/state'
+require 'golem/model/event'
+require 'golem/model/transition'
+require 'golem/model/callback'
+require 'golem/model/condition'
+
+require 'golem/dsl/event_def'
+
+module Golem
+  module DSL
+    class StateDef
+      def initialize(machine, state_name, options = {}, &block)
+        @machine = machine
+        @state = @machine.get_or_define_state(state_name)
+        @options = options
+        instance_eval(&block) if block
+      end
+
+      def on(event_name, options = {}, &block)
+        Golem::DSL::EventDef.new(@machine, @state, event_name, options, &block)
+      end
+
+      def enter(callback = nil, &block)
+        raise Golem::DefinitionSyntaxError, "Provide either a callback method or a block, not both." if callback && block
+        @state.callbacks[:on_enter] = Golem::Model::Callback.new(block || callback)
+      end
+
+      def exit(callback = nil, &block)
+        raise Golem::DefinitionSyntaxError, "Provide either a callback method or a block, not both." if callback && block
+        @state.callbacks[:on_exit] = Golem::Model::Callback.new(block || callback)
+      end
+    end
+  end
+end

data/lib/golem/dsl/state_machine_def.rb

@@ -0,0 +1,73 @@
+require 'golem/model/state_machine'
+require 'golem/model/state'
+require 'golem/model/callback'
+
+require 'golem/dsl/state_def'
+
+module Golem
+  module DSL
+    class StateMachineDef
+      attr_reader :machine_name
+
+      def initialize(klass, machine_name = nil, &block)
+        @klass = klass # this is the Class that we to endow with FSM behaviour
+        @machine = Golem::Model::StateMachine.new(machine_name)
+        instance_eval(&block) if block
+      end
+
+      def machine
+        @machine
+      end
+
+      def state(state_name, options = {}, &block)
+        Golem::DSL::StateDef.new(@machine, state_name, options, &block)
+      end
+
+      def all_states
+        @machine.all_states.collect{|state| StateDef.new(@machine, state.name)}
+      end
+
+      def initial_state(state)
+        @machine.initial_state = @machine.get_or_define_state(state)
+      end
+
+      # Sets or returns the state_attribute name.
+      def state_attribute(attribute = nil)
+        if attribute.nil?
+          @state_attribute
+        else
+          @state_attribute = attribute
+        end
+      end
+
+      # Sets the state_attribute name.
+      def state_attribute=(attribute)
+        @state_attribute = attribute
+      end
+
+      def on_all_transitions(callback = nil, &block)
+        raise Golem::DefinitionSyntaxError, "A callback or block must be given for on_all_transitions" unless
+          (callback || block)
+        raise Golem::DefinitionSyntaxError, "Either a callback or block, not both, must be given for on_all_transitions" if
+          (callback && block)
+        callback ||= block
+        unless callback.kind_of?(Golem::Model::Callback)
+          callback = Golem::Model::Callback.new(callback)
+        end
+        @machine.on_all_transitions = callback
+      end
+
+      def on_all_events(callback = nil, &block)
+        raise Golem::DefinitionSyntaxError, "A callback or block must be given for on_all_events" unless
+          (callback || block)
+        raise Golem::DefinitionSyntaxError, "Either a callback or block, not both, must be given for on_all_events" if
+          (callback && block)
+        callback ||= block
+        unless callback.kind_of?(Golem::Model::Callback)
+          callback = Golem::Model::Callback.new(callback)
+        end
+        @machine.on_all_events = callback
+      end
+    end
+  end
+end