edge-state-machine 0.0.2 → 0.0.3

data/README.rdoc

@@ -1,14 +1,9 @@
-= Travis Build Status
-
-{<img src="https://secure.travis-ci.org/danpersa/edge-state-machine.png"/>}[http://travis-ci.org/danpersa/edge-state-machine]
-
 = Edge State Machine
 
-The gem is based on Rick Olson's code of ActiveModel::StateMachine,
-axed from ActiveModel in {this
-commit}[http://github.com/rails/rails/commit/db49c706b62e7ea2ab93f05399dbfddf5087ee0c].
+Edge state machine wants to be a complete state machine solution.
+It offers support for ActiveRecord and Mongoid
 
-And on Krzysiek Heród's gem, {Transitions}[https://github.com/netizer/transitions], which added Mongoid support.
+{<img src="https://secure.travis-ci.org/danpersa/edge-state-machine.png"/>}[http://travis-ci.org/danpersa/edge-state-machine]
 
 == Installation
 
@@ -60,4 +55,12 @@ If you're using Rails + Mongoid + Bundler
     event :available do
       transitions :to => :available, :from => [:out_of_stock], :on_transition => :send_alerts
     end
-  end
+  end
+
+= Credits
+
+The gem is based on Rick Olson's code of ActiveModel::StateMachine,
+axed from ActiveModel in {this
+commit}[http://github.com/rails/rails/commit/db49c706b62e7ea2ab93f05399dbfddf5087ee0c].
+
+And on Krzysiek Heród's gem, {Transitions}[https://github.com/netizer/transitions], which added Mongoid support.

data/lib/active_record/edge-state-machine.rb

@@ -5,28 +5,73 @@ module ActiveRecord
     included do
       include ::EdgeStateMachine
       after_initialize :set_initial_state
-      validates_presence_of :state
+      validate :state_variables_presence
       validate :state_inclusion
     end
 
+    # The optional options argument is passed to find when reloading so you may
+    # do e.g. record.reload(:lock => true) to reload the same record with an
+    # exclusive row lock.
+    def reload(options = nil)
+      super.tap do
+        @current_states = {}
+      end
+    end
+
     protected
 
-    def write_state(state_machine, state)
-      self.state = state.to_s
-      save!
+    def load_from_persistence(machine_name)
+      machine = self.class.state_machines[machine_name]
+      send machine.persisted_variable_name.to_s
     end
 
-    def read_state(state_machine)
-      self.state.to_sym
+    def save_to_persistence(new_state, machine_name, options = {})
+      machine = self.class.state_machines[machine_name]
+      send("#{machine.persisted_variable_name}=".to_sym, new_state)
+      save! if options[:save]
     end
 
     def set_initial_state
-      self.state ||= self.class.state_machine.initial_state.to_s
+      # set the initial state for each state machine in this class
+      self.class.state_machines.keys.each do |machine_name|
+        machine = self.class.state_machines[machine_name]
+
+        if persisted_variable_value(machine.persisted_variable_name).blank?
+          if load_from_persistence(machine_name)
+            send("#{machine.persisted_variable_name}=".to_sym, load_from_persistence(machine_name))
+          else
+            send("#{machine.persisted_variable_name}=".to_sym, machine.initial_state_name)
+          end
+        end
+      end
+    end
+
+    def persisted_variable_value(name)
+      send(name.to_s)
+    end
+
+    def state_variables_presence
+      # validate that state is in the right set of values
+      self.class.state_machines.keys.each do |machine_name|
+        machine = self.class.state_machines[machine_name]
+        validates_presence_of machine.persisted_variable_name.to_sym
+      end
     end
 
     def state_inclusion
-      unless self.class.state_machine.states.map{|s| s.name.to_s }.include?(self.state.to_s)
-        self.errors.add(:state, :inclusion, :value => self.state)
+      # validate that state is in the right set of values
+      self.class.state_machines.keys.each do |machine_name|
+        machine = self.class.state_machines[machine_name]
+        unless machine.states.keys.include?(persisted_variable_value(machine.persisted_variable_name).to_sym)
+          self.errors.add(machine.persisted_variable_name.to_sym, :inclusion, :value => persisted_variable_value(machine.persisted_variable_name))
+        end
+      end
+    end
+
+    module ClassMethods
+      def add_scope(state, machine_name)
+        machine = state_machines[machine_name]
+        scope state.name, where(machine.persisted_variable_name.to_sym => state.name.to_s)
       end
     end
   end

data/lib/edge-state-machine/event.rb

@@ -2,106 +2,35 @@ module EdgeStateMachine
   class Event
     attr_reader :name, :success, :timestamp
 
-    def initialize(machine, name, options = {}, &block)
-      @machine, @name, @transitions = machine, name, []
-      if machine
-        machine.klass.send(:define_method, "#{name}!") do |*args|
-          machine.fire_event(name, self, true, *args)
-        end
-
-        machine.klass.send(:define_method, name.to_s) do |*args|
-          machine.fire_event(name, self, false, *args)
-        end
-      end
-      update(options, &block)
+    def initialize(name, machine, &transitions)
+      @machine = machine
+      @name = name
+      @transitions = []
+      instance_eval(&transitions) if block_given?
     end
 
-    def fire(obj, to_state = nil, *args)
-      transitions = @transitions.select { |t| t.from == obj.current_state(@machine ? @machine.name : nil) }
-      raise InvalidTransition if transitions.size == 0
+    def fire(obj, options = {})
+      current_state = obj.current_state(@machine.name)
+      transition = @transitions.select{ |t| t.from.include? current_state.name }.first
 
-      next_state = nil
-      transitions.each do |transition|
-        next if to_state && !Array(transition.to).include?(to_state)
-        if transition.perform(obj)
-          next_state = to_state || Array(transition.to).first
-          transition.execute(obj, *args)
-          break
-        end
-      end
-      # Update timestamps on obj if a timestamp has been defined
-      update_event_timestamp(obj, next_state) if timestamp_defined?
-      next_state
-    end
+      raise NoTransitionFound.new("No transition found for event #{@name}") if transition.nil?
+      return false unless transition.possible?(obj)
 
-    def transitions_from_state?(state)
-      @transitions.any? { |t| t.from? state }
-    end
+      next_state = @machine.states[transition.find_next_state(obj)]
+      raise NoStateFound.new("Invalid state #{transition.to.to_s} for transition.") if next_state.nil?
+      transition.execute(obj)
 
-    def ==(event)
-      if event.is_a? Symbol
-        name == event
-      else
-        name == event.name
-      end
-    end
-    
-    # Has the timestamp option been specified for this event?
-    def timestamp_defined?
-      !@timestamp.nil?
-    end
+      current_state.execute_action(:exit, obj)
+      #klass._previous_state = current_state.name.to_s
+      next_state.execute_action(:enter, obj)
 
-    def update(options = {}, &block)
-      @success       = options[:success] if options.key?(:success)
-      self.timestamp = options[:timestamp] if options[:timestamp]
-      instance_eval(&block) if block
-      self
+      obj.set_current_state(next_state, @machine.name, options)
+      true
     end
-    
-    # update the timestamp attribute on obj
-    def update_event_timestamp(obj, next_state)
-      obj.send "#{timestamp_attribute_name(obj, next_state)}=", Time.now
-    end
-    
-    # Set the timestamp attribute.
-    # @raise [ArgumentError] timestamp should be either a String, Symbol or true
-    def timestamp=(value)
-      case value
-      when String, Symbol, TrueClass
-        @timestamp = value
-      else
-        raise ArgumentError, "timestamp must be either: true, a String or a Symbol"
-      end
-    end
-    
 
     private
-    
-    # Returns the name of the timestamp attribute for this event
-    # If the timestamp was simply true it returns the default_timestamp_name
-    # otherwise, returns the user-specified timestamp name
-    def timestamp_attribute_name(obj, next_state)
-      timestamp == true ? default_timestamp_name(obj, next_state) : @timestamp
-    end
-    
-    # If @timestamp is true, try a default timestamp name
-    def default_timestamp_name(obj, next_state)
-      at_name = "%s_at" % next_state
-      on_name = "%s_on" % next_state
-      case
-      when obj.respond_to?(at_name) then at_name
-      when obj.respond_to?(on_name) then on_name
-      else
-        raise NoMethodError, "Couldn't find a suitable timestamp field for event: #{@name}. 
-          Please define #{at_name} or #{on_name} in #{obj.class}"
-      end
-    end
-    
-
-    def transitions(trans_opts)
-      Array(trans_opts[:from]).each do |s|
-        @transitions << Transition.new(trans_opts.merge({:from => s.to_sym}))
-      end
+    def transition(trans_opts)
+      @transitions << EdgeStateMachine::Transition.new(trans_opts)
     end
   end
 end

data/lib/edge-state-machine/exception.rb

@@ -0,0 +1,8 @@
+module EdgeStateMachine
+  class InvalidTransition     < StandardError; end
+  class InvalidMethodOverride < StandardError; end
+  class NoTransitionFound < Exception; end
+  class NoStateFound < Exception; end
+  class NoEventFound < Exception; end
+  class NoGuardFound < Exception; end
+end

data/lib/edge-state-machine/machine.rb

@@ -1,85 +1,40 @@
 module EdgeStateMachine
   class Machine
-    attr_writer :initial_state
-    attr_accessor :states, :events, :state_index
-    attr_reader :klass, :name, :auto_scopes
+    attr_accessor :states, :events, :klass, :persisted_variable_name
+    attr_reader :name, :initial_state_name
 
-    def initialize(klass, name, options = {}, &block)
-      @klass, @name, @states, @state_index, @events = klass, name, [], {}, {}
-      update(options, &block)
+    def initialize(klass, name, &block)
+      @klass = klass
+      @name = name
+      @states = Hash.new
+      @events = Hash.new
+      instance_eval(&block) if block_given?
     end
 
-    def initial_state
-      @initial_state ||= (states.first ? states.first.name : nil)
+    def initial_state(name)
+      @initial_state_name = name
     end
 
-    def update(options = {}, &block)
-      @initial_state = options[:initial] if options.key?(:initial)
-      @auto_scopes = options[:auto_scopes]
-      instance_eval(&block) if block
-      include_scopes if @auto_scopes && defined?(ActiveRecord::Base) && @klass < ActiveRecord::Base
-      self
+    def persisted_to(name)
+      @persisted_variable_name = name
     end
 
-    def fire_event(event, record, persist, *args)
-      state_index[record.current_state(@name)].call_action(:exit, record)
-      if new_state = @events[event].fire(record, nil, *args)
-        state_index[new_state].call_action(:enter, record)
-
-        if record.respond_to?(event_fired_callback)
-          record.send(event_fired_callback, record.current_state, new_state, event)
-        end
-
-        record.current_state(@name, new_state, persist)
-        record.send(@events[event].success) if @events[event].success
-        true
-      else
-        if record.respond_to?(event_failed_callback)
-          record.send(event_failed_callback, event)
-        end
-
-        false
-      end
-    end
-
-    def states_for_select
-      states.map { |st| [st.display_name, st.name.to_s] }
-    end
-
-    def events_for(state)
-      events = @events.values.select { |event| event.transitions_from_state?(state) }
-      events.map! { |event| event.name }
+    def create_scopes(bool = false)
+      @create_scopes = bool
     end
 
-    def current_state_variable
-      "@#{@name}_current_state"
+    def create_scopes?
+      @create_scopes
     end
 
-    private
-
-    def state(name, options = {})
-      @states << (state_index[name] ||= State.new(name, :machine => self)).update(options)
+    def state(name, &state)
+      state = EdgeStateMachine::State.new(name, &state)
+      @initial_state_name ||= state.name
+      @states[name.to_sym] = state
     end
 
-    def event(name, options = {}, &block)
-      (@events[name] ||= Event.new(self, name)).update(options, &block)
-    end
-
-    def event_fired_callback
-      @event_fired_callback ||= (@name == :default ? '' : "#{@name}_") + 'event_fired'
-    end
-
-    def event_failed_callback
-      @event_failed_callback ||= (@name == :default ? '' : "#{@name}_") + 'event_failed'
-    end
-
-    def include_scopes
-      @states.each do |state|
-        state_name = state.name.to_s
-        raise InvalidMethodOverride if @klass.respond_to?(state_name)
-        @klass.scope state_name, @klass.where(:state => state_name)
-      end
+    def event(name, &transitions)
+      @events[name.to_sym] ||= EdgeStateMachine::Event.new(name, self, &transitions)
     end
   end
-end
-
+end

data/lib/edge-state-machine/state.rb

@@ -2,44 +2,46 @@ module EdgeStateMachine
   class State
     attr_reader :name, :options
 
-    def initialize(name, options = {})
+    def initialize(name, &block)
       @name = name
-      if machine = options.delete(:machine)
-        machine.klass.define_state_query_method(name)
-      end
-      update(options)
+      @options = Hash.new
+      instance_eval(&block) if block_given?
     end
 
-    def ==(state)
-      if state.is_a? Symbol
-        name == state
-      else
-        name == state.name
-      end
+    def enter(method = nil, &block)
+      @options[:enter] = method.nil? ? block : method
     end
 
-    def call_action(action, record)
-      action = @options[action]
+    def exit(method = nil, &block)
+      @options[:exit] = method.nil? ? block : method
+    end
+
+    def execute_action(action, base)
+      action = @options[action.to_sym]
       case action
       when Symbol, String
-        record.send(action)
+        base.send(action)
       when Proc
-        action.call(record)
+        action.call(base)
       end
     end
 
-    def display_name
-      @display_name ||= name.to_s.gsub(/_/, ' ').capitalize
+    def use_display_name(display_name)
+      @display_name = display_name
     end
 
-    def for_select
-      [display_name, name.to_s]
+    def display_name
+      @display_name ||= name.to_s.gsub(/_/, ' ').capitalize
     end
 
-    def update(options = {})
-      @display_name = options.delete(:display) if options.key?(:display)
-      @options = options
-      self
+    def ==(state)
+      if state.is_a? Symbol
+        name == state
+      elsif state.is_a? String
+        name == state
+      else
+        name == state.name
+      end
     end
   end
 end

data/lib/edge-state-machine/transition.rb

@@ -3,36 +3,37 @@ module EdgeStateMachine
     attr_reader :from, :to, :options
 
     def initialize(opts)
-      @from, @to, @guard, @on_transition = opts[:from], opts[:to], opts[:guard], opts[:on_transition]
-      @options = opts
+      @from, @to, @guard, @on_transition = [opts[:from]].flatten, [opts[:to]].flatten, opts[:guard], [opts[:on_transition]].flatten
     end
 
-    def perform(obj)
-      case @guard
-      when Symbol, String
-        obj.send(@guard)
-      when Proc
-        @guard.call(obj)
+    def find_next_state(obj)
+      # if we have many states we can go but no guard
+      if @guard.nil? && @to.size > 1
+        raise NoGuardFound.new("There are many possible 'to' states but there is no 'guard' to decide which state to go")
+      end
+      if @guard
+        return execute_action(@guard, obj)
       else
-        true
+        return @to.first
       end
     end
 
-    def execute(obj, *args)
-      case @on_transition
-      when Symbol, String
-        obj.send(@on_transition, *args)
-      when Proc
-        @on_transition.call(obj, *args)
-      when Array
-        @on_transition.each do |callback|
-          # Yes, we're passing always the same parameters for each callback in here.
-          # We should probably drop args altogether in case we get an array.
-          obj.send(callback, *args)
+    def possible?(obj)
+      next_state = find_next_state(obj)
+      return true if @to.include? next_state
+      false
+    end
+
+    def execute(obj)
+      @on_transition.each do |transition|
+        case transition
+        when Symbol, String
+          obj.send(transition)
+        when Proc
+          transition.call(obj)
+        else
+          raise ArgumentError, "You can only pass a Symbol, a String or a Proc to 'on_transition' - got #{transition.class}." unless transition.nil?
         end
-      else
-        # TODO We probably should check for this in the constructor and not that late.
-        raise ArgumentError, "You can only pass a Symbol, a String, a Proc or an Array to 'on_transition' - got #{@on_transition.class}." unless @on_transition.nil?
       end
     end
 
@@ -40,8 +41,14 @@ module EdgeStateMachine
       @from == obj.from && @to == obj.to
     end
 
-    def from?(value)
-      @from == value
+    private
+    def execute_action(action, base)
+      case action
+      when Symbol, String
+        base.send(action)
+      when Proc
+        action.call(base)
+      end
     end
   end
 end

data/lib/edge-state-machine/version.rb

@@ -1,3 +1,3 @@
 module EdgeStateMachine
-  VERSION = "0.0.2"
+  VERSION = "0.0.3"
 end

data/lib/edge-state-machine.rb

@@ -2,11 +2,15 @@ require "edge-state-machine/event"
 require "edge-state-machine/machine"
 require "edge-state-machine/state"
 require "edge-state-machine/transition"
+require "edge-state-machine/exception"
 require "edge-state-machine/version"
 
 module EdgeStateMachine
-  class InvalidTransition     < StandardError; end
-  class InvalidMethodOverride < StandardError; end
+
+  def self.included(base)
+    base.extend(ClassMethods)
+    base.send :include, InstanceMethods
+  end
 
   module ClassMethods
     def inherited(klass)
@@ -22,52 +26,63 @@ module EdgeStateMachine
       @state_machines = value ? value.dup : nil
     end
 
-    def state_machine(name = nil, options = {}, &block)
-      if name.is_a?(Hash)
-        options = name
-        name    = nil
+    def state_machine(name = :default, &block)
+      machine = Machine.new(self, name, &block)
+      state_machines[name] ||= machine
+
+      machine.persisted_variable_name ||= :state
+
+      machine.states.values.each do |state|
+        state_name = state.name
+        define_method "#{state_name}?" do
+          state_name == current_state(name).name
+        end
+        add_scope(state, name) if machine.create_scopes?
       end
-      name ||= :default
-      state_machines[name] ||= Machine.new(self, name)
-      block ? state_machines[name].update(options, &block) : state_machines[name]
-    end
 
-    def define_state_query_method(state_name)
-      name = "#{state_name}?"
-      undef_method(name) if method_defined?(name)
-      define_method(name) do
-        current_state.to_s == state_name.to_s
+      machine.events.keys.each do |key|
+        define_method "#{key}" do
+          fire_event(machine.name, {:save => false}, key)
+        end
+
+        define_method "#{key}!" do
+          fire_event(machine.name, {:save => true}, key)
+        end
       end
     end
   end
 
-  def self.included(base)
-    base.extend(ClassMethods)
-  end
+  module InstanceMethods
+    attr_writer :current_state
 
-  def current_state(name = nil, new_state = nil, persist = false)
-    sm   = self.class.state_machine(name)
-    ivar = sm.current_state_variable
-    if name && new_state
-      if persist && respond_to?(:write_state)
-        write_state(sm, new_state)
-      end
+    def initial_state_name(name = :default)
+      machine = self.class.state_machines[name]
+      return machine.initial_state_name
+    end
 
-      if respond_to?(:write_state_without_persistence)
-        write_state_without_persistence(sm, new_state)
+    def current_state(name = :default)
+      @current_states ||= {}
+      machine = self.class.state_machines[name]
+      if (respond_to? :load_from_persistence)
+        @current_states[name] ||= self.class.state_machines[name].states[load_from_persistence(name).to_sym]
       end
+      @current_states[name] ||= machine.states[machine.initial_state_name]
+    end
 
-      instance_variable_set(ivar, new_state)
-    else
-      instance_variable_set(ivar, nil) unless instance_variable_defined?(ivar)
-      value = instance_variable_get(ivar)
-      return value if value
+    def current_state_name(name = :default)
+      current_state(name).name
+    end
 
-      if respond_to?(:read_state)
-        value = instance_variable_set(ivar, read_state(sm))
-      end
+    def fire_event(name = :default, options = {}, event_name)
+      machine = self.class.state_machines[name]
+      event = machine.events[event_name]
+      raise Stateflow::NoEventFound.new("No event matches #{event_name}") if event.nil?
+      event.fire(self, options)
+    end
 
-      value || sm.initial_state
+    def set_current_state(new_state, machine_name = :default, options = {})
+      save_to_persistence(new_state.name.to_s, machine_name, options) if self.respond_to? :save_to_persistence
+      @current_states[machine_name] = new_state
     end
   end
 end