finite_machine 0.10.2 → 0.11.0

data/lib/finite_machine/state_definition.rb

@@ -0,0 +1,66 @@
+# encoding: utf-8
+
+module FiniteMachine
+  # A class responsible for defining state query methods on state machine
+  #
+  # Used by {TranstionBuilder} to add state query definition
+  # to the {StateMachine} instance.
+  #
+  # @api private
+  class StateDefinition
+    include Threadable
+
+    # Initialize a StateDefinition
+    #
+    # @param [StateMachine] machine
+    #
+    # @api public
+    def initialize(machine)
+      self.machine = machine
+    end
+
+    # Define query methods for states
+    #
+    # @param [Hash] states
+    #   the states that require query helpers
+    #
+    # @return [nil]
+    #
+    # @api public
+    def apply(states)
+      define_state_query_methods(states)
+    end
+
+    private
+
+    # The current state machine
+    attr_threadsafe :machine
+
+    # Define helper state mehods for the transition states
+    #
+    # @param [Hash] states
+    #   the states to define helpers for
+    #
+    # @return [nil]
+    #
+    # @api private
+    def define_state_query_methods(states)
+      states.to_a.flatten.each do |state|
+        define_state_query_method(state)
+      end
+    end
+
+    # Define state helper method
+    #
+    # @param [Symbol] state
+    #   the state to define helper for
+    #
+    # @api private
+    def define_state_query_method(state)
+      return if machine.respond_to?("#{state}?")
+      machine.send(:define_singleton_method, "#{state}?") do
+        machine.is?(state.to_sym)
+      end
+    end
+  end # StateDefinition
+end # FiniteMachine

data/lib/finite_machine/state_machine.rb

@@ -14,92 +14,87 @@ module FiniteMachine
     # Final state, defaults to :none
     attr_threadsafe :final_state
 
-    # Current state
-    attr_threadsafe :state
+    # The prefix used to name events.
+    attr_threadsafe :namespace
 
-    # Events DSL
-    attr_threadsafe :events_dsl
+    # The state machine environment
+    attr_threadsafe :env
 
-    # Errors DSL
-    attr_threadsafe :errors
+    # The state machine event definitions
+    attr_threadsafe :events_chain
 
-    # The prefix used to name events.
-    attr_threadsafe :namespace
+    # Errors DSL
+    #
+    # @return [ErrorsDSL]
+    #
+    # @api private
+    attr_threadsafe :errors_dsl
 
-    # The events and their transitions.
-    attr_threadsafe :transitions
+    # Events DSL
+    #
+    # @return [EventsDSL]
+    #
+    # @api private
+    attr_threadsafe :events_dsl
 
     # The state machine observer
+    #
+    # @return [Observer]
+    #
+    # @api private
     attr_threadsafe :observer
 
+    # Current state
+    #
+    # @return [Symbol]
+    #
+    # @api private
+    attr_threadsafe :state
+
     # The state machine subscribers
+    #
+    # @return [Subscribers]
+    #
+    # @api private
     attr_threadsafe :subscribers
 
-    # The state machine environment
-    attr_threadsafe :env
-
-    # The previous state before transition
-    attr_threadsafe :previous_state
-
-    # The state machine event definitions
-    attr_threadsafe :events_chain
-
     # Allow or not logging of transitions
     attr_threadsafe :log_transitions
 
     def_delegators :@dsl, :initial, :terminal, :target, :trigger_init,
                    :alias_target
 
-    def_delegator :@events_dsl, :event
-
-    def_delegators :@events_chain, :check_choice_conditions, :select_transition,
-                   :select_choice_transition
+    def_delegator :events_dsl, :event
 
     # Initialize state machine
     #
     # @api private
     def initialize(*args, &block)
       attributes     = args.last.is_a?(Hash) ? args.pop : {}
+      self.event_queue = EventQueue.new
+
       @initial_state = DEFAULT_STATE
-      @subscribers   = Subscribers.new(self)
+      @async_proxy   = AsyncProxy.new(self)
+      @subscribers   = Subscribers.new
       @observer      = Observer.new(self)
-      @transitions   = Hash.new { |hash, name| hash[name] = Hash.new }
-      @events_chain  = EventsChain.new(self)
+      @events_chain  = EventsChain.new
       @env           = Env.new(self, [])
       @events_dsl    = EventsDSL.new(self)
-      @errors        = ErrorsDSL.new(self)
+      @errors_dsl    = ErrorsDSL.new(self)
       @dsl           = DSL.new(self, attributes)
 
       @dsl.call(&block) if block_given?
       trigger_init
     end
 
+    # Subscribe observer for event notifications
+    #
     # @example
     #   machine.subscribe(Observer.new(machine))
     #
     # @api public
     def subscribe(*observers)
-      @subscribers.subscribe(*observers)
-    end
-
-    # TODO:  use trigger to actually fire state machine events!
-    # Notify about event all the subscribers
-    #
-    # @param [FiniteMachine::HookEvent] :event_type
-    #   The hook event type.
-    # @param [FiniteMachine::Transition] :event_transition
-    #   The event transition.
-    # @param [Array[Object]] :data
-    #   The data associated with the hook event.
-    #
-    # @return [nil]
-    #
-    # @api public
-    def notify(event_type, event_transition, *data)
-      sync_shared do
-        hook_event = event_type.build(state, event_transition, *data)
-        subscribers.visit(hook_event)
-      end
+      sync_exclusive { subscribers.subscribe(*observers) }
     end
 
     # Help to mark the event as synchronous
@@ -118,7 +113,6 @@ module FiniteMachine
     #
     # @api public
     def async(method_name = nil, *args, &block)
-      @async_proxy = AsyncProxy.new(self)
       if method_name
         @async_proxy.method_missing method_name, *args, &block
       else
@@ -162,18 +156,19 @@ module FiniteMachine
     #
     # @api public
     def states
-      sync_shared do
-        event_names.map { |event| transitions[event].to_a }.flatten.uniq
-      end
+      sync_shared { events_chain.states }
     end
 
     # Retireve all event names
     #
+    # @example
+    #   fsm.event_names # => [:init, :start, :stop]
+    #
     # @return [Array[Symbol]]
     #
     # @api public
     def event_names
-      sync_shared { transitions.keys }
+      sync_shared { events_chain.events }
     end
 
     # Checks if event can be triggered
@@ -189,11 +184,9 @@ module FiniteMachine
     # @return [Boolean]
     #
     # @api public
-    def can?(*args, &block)
-      event       = args.shift
-      valid_state = transitions[event].key?(current)
-      valid_state ||= transitions[event].key?(ANY_STATE)
-      valid_state && events_chain.valid_event?(event, *args, &block)
+    def can?(*args)
+      event_name  = args.shift
+      events_chain.can_perform?(event_name, current, *args)
     end
 
     # Checks if event cannot be triggered
@@ -230,82 +223,167 @@ module FiniteMachine
       sync_exclusive { self.state = state }
     end
 
-    # String representation of this machine
+    # Check if state is reachable
     #
-    # @return [String]
+    # @param [Symbol] event_name
+    #   the event name for all transitions
     #
-    # @api public
-    def inspect
+    # @return [Boolean]
+    #
+    # @api private
+    def valid_state?(event_name)
+      current_states = events_chain.states_for(event_name)
+      current_states.any? { |state| state == current || state == ANY_STATE }
+    end
+
+    # Notify about event all the subscribers
+    #
+    # @param [HookEvent] :hook_event_type
+    #   The hook event type.
+    # @param [FiniteMachine::Transition] :event_transition
+    #   The event transition.
+    # @param [Array[Object]] :data
+    #   The data associated with the hook event.
+    #
+    # @return [nil]
+    #
+    # @api private
+    def notify(hook_event_type, event_name, from, *data)
       sync_shared do
-        "<##{self.class}:0x#{object_id.to_s(16)} @states=#{states}, " \
-        "@events=#{event_names}, @transitions=#{transitions.inspect}>"
+        hook_event = hook_event_type.build(current, event_name, from)
+        subscribers.visit(hook_event, *data)
       end
     end
 
-    private
-
-    # Check if state is reachable
-    #
-    # @param [FiniteMachine::Transition]
+    # Attempt performing event trigger for valid state
     #
     # @return [Boolean]
+    #   true is trigger successful, false otherwise
     #
     # @api private
-    def valid_state?(event_transition)
-      current_states = transitions[event_transition.name].keys
-      if !current_states.include?(state) && !current_states.include?(ANY_STATE)
+    def try_trigger(event_name)
+      if valid_state?(event_name)
+        yield
+      else
         exception = InvalidStateError
         catch_error(exception) ||
-          fail(exception, "inappropriate current state '#{state}'")
-        return false
+          fail(exception, "inappropriate current state '#{current}'")
+
+        false
       end
-      return true
     end
 
-    # Performs transition
+    # Trigger transition event with data
     #
-    # @param [Transition] event_transition
-    # @param [Array] args
+    # @param [Symbol] event_name
+    #   the event name
+    # @param [Array] data
     #
-    # @return [Integer]
-    #   the status code for the transition
+    # @return [Boolean]
+    #   true when transition is successful, false otherwise
     #
-    # @api private
-    def transition(event_transition, *args, &block)
+    # @api public
+    def trigger!(event_name, *data, &block)
       sync_exclusive do
-        notify HookEvent::Before, event_transition, *args
+        from = current # Save away current state
+
+        notify HookEvent::Before, event_name, from, *data
 
-        if valid_state?(event_transition) && event_transition.valid?(*args, &block)
-          notify HookEvent::Exit, event_transition, *args
+        status = try_trigger(event_name) do
+          if can?(event_name, *data)
+            notify HookEvent::Exit, event_name, from, *data
 
-          begin
-            event_transition.execute(*args)
-            Logger.report_transition(event_transition, *args) if log_transitions
+            stat = transition!(event_name, *data, &block)
 
-            notify HookEvent::Transition, event_transition, *args
-          rescue Exception => e
-            catch_error(e) || raise_transition_error(e)
+            notify HookEvent::Transition, event_name, from, *data
+            notify HookEvent::Enter, event_name, from, *data
+          else
+            stat = false
           end
+          stat
+        end
+
+        notify HookEvent::After, event_name, from, *data
+
+        status
+      end
+    end
 
-          notify HookEvent::Enter, event_transition, *args
+    # Trigger transition event without raising any errors
+    #
+    # @param [Symbol] event_name
+    #
+    # @return [Boolean]
+    #   true on successful transition, false otherwise
+    #
+    # @api public
+    def trigger(event_name, *data, &block)
+      trigger!(event_name, *data, &block)
+    rescue InvalidStateError, TransitionError
+      false
+    end
 
-          notify HookEvent::After, event_transition, *args
+    # Find available state to transition to and transition
+    #
+    # @param [Symbol] event_name
+    #
+    # @api private
+    def transition!(event_name, *data, &block)
+      from_state = current
+      to_state   = events_chain.move_to(event_name, from_state, *data)
 
-          event_transition.same?(state) ? NOTRANSITION : SUCCEEDED
-        else
-          notify HookEvent::After, event_transition, *args
+      block.call(from_state, to_state) if block
 
-          CANCELLED
-        end
+      if log_transitions
+        Logger.report_transition(event_name, from_state, to_state, *data)
       end
+
+      try_trigger(event_name) { transition_to!(to_state) }
+    end
+
+    def transition(event_name, *data, &block)
+      transition!(event_name, *data, &block)
+    rescue InvalidStateError, TransitionError
+      false
     end
 
+    # Update this state machine state to new one
+    #
+    # @param [Symbol] new_state
+    #
+    # @raise [TransitionError]
+    #
+    # @api private
+    def transition_to!(new_state)
+      from_state = current
+      self.state = new_state
+      self.initial_state = new_state if from_state == DEFAULT_STATE
+      true
+    rescue Exception => e
+      catch_error(e) || raise_transition_error(e)
+    end
+
+    # String representation of this machine
+    #
+    # @return [String]
+    #
+    # @api public
+    def inspect
+      sync_shared do
+        "<##{self.class}:0x#{object_id.to_s(16)} @states=#{states}, " \
+        "@events=#{event_names}, " \
+        "@transitions=#{events_chain.state_transitions}>"
+      end
+    end
+
+    private
+
     # Raise when failed to transition between states
     #
     # @param [Exception] error
     #   the error to describe
     #
-    # @raise [FiniteMachine::TransitionError]
+    # @raise [TransitionError]
     #
     # @api private
     def raise_transition_error(error)