finite_machine 0.10.2 → 0.11.0

data/lib/finite_machine/events_chain.rb

@@ -1,52 +1,127 @@
 # encoding: utf-8
 
+require 'finite_machine/undefined_transition'
+
 module FiniteMachine
-  # A class responsible for storing chain of events
+  # A class responsible for storing chain of events.
+  #
+  # Used internally by {StateMachine}.
+  #
+  # @api private
   class EventsChain
     include Threadable
     extend Forwardable
 
-    # The current state machine
-    attr_threadsafe :machine
-
     # The chain of events
+    #
+    # @api private
     attr_threadsafe :chain
 
-    def_delegators :@chain, :[], :empty?
+    def_delegators :@chain, :empty?, :size
 
     # Initialize a EventsChain
     #
-    # @param [StateMachine] machine
-    #   the state machine
+    # @api private
+    def initialize
+      @chain = {}
+    end
+
+    # Check if event is present
+    #
+    # @example
+    #   events_chain.exists?(:go) # => true
+    #
+    # @param [Symbol] name
+    #   the event name
+    #
+    # @return [Boolean]
+    #   true if event is present, false otherwise
     #
     # @api public
-    def initialize(machine)
-      @machine = machine
-      @chain   = {}
+    def exists?(name)
+      !chain[name].nil?
     end
 
-    # Insert transition under given event name
+    # Add transition under name
     #
-    # @param [Symbol] name
-    #  the event name
+    # @param [Symbol] the event name
     #
-    # @param [Transition]
+    # @param [Transition] transition
+    #   the transition to add under event name
     #
     # @return [nil]
     #
     # @api public
-    def insert(name, transition)
-      return false unless chain[name]
-      chain[name] << transition
+    def add(name, transition)
+      if exists?(name)
+        chain[name] << transition
+      else
+        chain[name] = [transition]
+      end
+      self
     end
 
-    # Add event under name
+    # Finds transitions for the event name
     #
-    # @return [nil]
+    # @param [Symbol] name
+    #
+    # @example
+    #   events_chain[:start] # => []
+    #
+    # @return [Array[Transition]]
+    #   the transitions matching event name
+    #
+    # @api public
+    def find(name)
+      chain.fetch(name) { [] }
+    end
+    alias_method :[], :find
+
+    # Retrieve all event names
+    #
+    # @example
+    #   events_chain.events # => [:init, :start, :stop]
+    #
+    # @return [Array[Symbol]]
+    #   All event names
+    #
+    # @api public
+    def events
+      chain.keys
+    end
+
+    # Retreive all unique states
+    #
+    # @example
+    #   events_chain.states # => [:yellow, :green, :red]
+    #
+    # @return [Array[Symbol]]
+    #   the array of all unique states
+    #
+    # @api public
+    def states
+      chain.values.flatten.map(&:states).map(&:to_a).flatten.uniq
+    end
+
+    # Retrieves all state transitions
+    #
+    # @return [Array[Hash]]
+    #
+    # @api public
+    def state_transitions
+      chain.values.flatten.map(&:states)
+    end
+
+    # Retrieve from states for the event name
+    #
+    # @param [Symbol] event_name
+    #
+    # @example
+    #   events_chain.states_for(:start) # => [:yellow, :green]
     #
     # @api public
-    def add(name, event)
-      chain[name] = event
+    def states_for(name)
+      find(name).map(&:states).flat_map(&:keys)
     end
 
     # Check if event is valid and transition can be performed
@@ -54,23 +129,47 @@ module FiniteMachine
     # @return [Boolean]
     #
     # @api public
-    def valid_event?(event, *args, &block)
-      chain[event].next_transition.valid?(*args, &block)
+    def can_perform?(name, from_state, *conditions)
+      !match_transition_with(name, from_state, *conditions).nil?
     end
 
-    # Select transition that passes constraints condition
+    # Check if event has branching choice transitions or not
+    #
+    # @example
+    #   events_chain.choice_transition?(:go, :green) # => true
     #
     # @param [Symbol] name
     #   the event name
     #
-    # @return [Transition]
+    # @param [Symbol] from_state
+    #   the transition from state
+    #
+    # @return [Boolean]
+    #   true if transition has any branches, false otherwise
     #
     # @api public
-    def select_transition(name, *args)
-      chain[name].find_transition(*args)
+    def choice_transition?(name, from_state)
+      find(name).select { |trans| trans.matches?(from_state) }.size > 1
+    end
+
+    # Find transition without checking conditions
+    #
+    # @param [Symbol] name
+    #   the event name
+    #
+    # @param [Symbol] from_state
+    #   the transition from state
+    #
+    # @return [Transition, nil]
+    #   returns transition, nil otherwise
+    #
+    # @api private
+    def match_transition(name, from_state)
+      find(name).find { |trans| trans.matches?(from_state) }
     end
 
-    # Examine choice transitions to find one matching condition
+    # Examine transitions for event name that start in from state
+    # and find one matching condition.
     #
     # @param [Symbol] name
     #   the event name
@@ -82,24 +181,71 @@ module FiniteMachine
     #   The choice transition that matches
     #
     # @api public
-    def select_choice_transition(name, from_state, *args, &block)
-      chain[name].state_transitions.find do |trans|
-        [from_state, ANY_STATE].include?(trans.from_state) &&
-        trans.check_conditions(*args, &block)
+    def match_transition_with(name, from_state, *conditions)
+      find(name).find do |trans|
+        trans.matches?(from_state) &&
+        trans.check_conditions(*conditions)
       end
     end
 
-    # Check if any of the transition constraints passes
+    # Select transition that matches conditions
     #
     # @param [Symbol] name
     #   the event name
+    # @param [Symbol] from_state
+    #   the transition from state
+    # @param [Array[Object]] conditions
+    #   the conditional data
     #
-    # @return [Boolean]
+    # @return [Transition]
+    #
+    # @api public
+    def select_transition(name, from_state, *conditions)
+      if choice_transition?(name, from_state)
+        match_transition_with(name, from_state, *conditions)
+      else
+        match_transition(name, from_state)
+      end
+    end
+
+    # Find state that this machine can move to
+    #
+    # @example
+    #   evenst_chain.move_to(:go, :green) # => :red
+    #
+    # @param [Symbol] name
+    #   the event name
+    #
+    # @param [Symbol] from_state
+    #   the transition from state
+    #
+    # @param [Array] conditions
+    #   the data associated with this transition
+    #
+    # @return [Symbol]
+    #   the transition `to` state
+    #
+    # @api public
+    def move_to(name, from_state, *conditions)
+      transition = select_transition(name, from_state, *conditions)
+      transition ||= UndefinedTransition.new(name)
+
+      transition.to_state(from_state)
+    end
+
+    # Set cancelled status for all transitions matching event name
+    #
+    # @param [Symbol] name
+    #   the event name
+    # @param [Symbol] status
+    #   true to cancel, false otherwise
+    #
+    # @return [nil]
     #
     # @api public
-    def check_choice_conditions(name, *args, &block)
-      chain[name].state_transitions.any? do |trans|
-        trans.current? && trans.check_conditions(*args, &block)
+    def cancel_transitions(name, status)
+      chain[name].each do |trans|
+        trans.cancelled = status
       end
     end
 

data/lib/finite_machine/hook_event.rb

@@ -6,86 +6,91 @@ module FiniteMachine
     include Threadable
     include Comparable
 
-    MESSAGE = :trigger
+    class Anystate < HookEvent; end
+
+    class Enter < Anystate; end
+
+    class Transition < Anystate; end
 
-    # HookEvent name
+    class Exit < Anystate; end
+
+    class Anyaction < HookEvent; end
+
+    class Before < Anyaction; end
+
+    class After < Anyaction; end
+
+    EVENTS = Anystate, Enter, Transition, Exit, Anyaction, Before, After
+
+    MESSAGE = :emit
+
+    # HookEvent state or action
     attr_threadsafe :name
 
     # HookEvent type
     attr_threadsafe :type
 
-    # Data associated with the event
-    attr_threadsafe :data
+    # The from state this hook has been fired
+    attr_threadsafe :from
 
-    # Transition associated with the event
-    attr_threadsafe :transition
+    # The event name triggering this hook event
+    attr_threadsafe :event_name
 
     # Instantiate a new HookEvent object
     #
     # @param [Symbol] name
     #   The action or state name
-    # @param [FiniteMachine::Transition]
-    #   The transition associated with this event.
-    # @param [Array[Object]] data
+    #
+    # @param [Symbol] event_name
+    #   The event name associated with this hook event.
     #
     # @example
-    #   HookEvent.new(:green, ...)
+    #   HookEvent.new(:green, :move, :green)
     #
-    # @return [Object]
+    # @return [self]
     #
     # @api public
-    def initialize(name, transition, *data)
+    def initialize(name, event_name, from)
       @name       = name
-      @transition = transition
-      @data       = *data
       @type       = self.class
+      @event_name = event_name
+      @from       = from
       freeze
     end
 
     # Build event hook
     #
     # @param [Symbol] :state
-    #   The state name.
-    # @param [FiniteMachine::Transition] :event_transition
-    #   The transition associted with this hook.
-    # @param [Array[Object]] :data
-    #   The data associated with this hook
+    #   The state or action name.
+    #
+    # @param [Symbol] :event_name
+    #   The event name associted with this hook.
     #
     # @return [self]
     #
     # @api public
-    def self.build(state, event_transition, *data)
-      state_or_action = self < Anystate ? state : event_transition.name
-      new(state_or_action, event_transition, *data)
+    def self.build(state, event_name, from)
+      state_or_action = self < Anystate ? state : event_name
+      new(state_or_action, event_name, from)
     end
 
     # Notify subscriber about this event
     #
+    # @param [Observer] subscriber
+    #   the object subscribed to be notified about this event
+    #
+    # @param [Array] data
+    #   the data associated with the triggered event
+    #
     # @return [nil]
     #
     # @api public
-    def notify(subscriber, *args, &block)
-      if subscriber.respond_to? MESSAGE
-        subscriber.public_send(MESSAGE, self, *args, &block)
+    def notify(subscriber, *data)
+      if subscriber.respond_to?(MESSAGE)
+        subscriber.public_send(MESSAGE, self, *data)
       end
     end
 
-    class Anystate < HookEvent; end
-
-    class Enter < Anystate; end
-
-    class Transition < Anystate; end
-
-    class Exit < Anystate; end
-
-    class Anyaction < HookEvent; end
-
-    class Before < Anyaction; end
-
-    class After < Anyaction; end
-
-    EVENTS = Anystate, Enter, Transition, Exit, Anyaction, Before, After
-
     # Extract event name
     #
     # @return [String] the event name
@@ -111,7 +116,7 @@ module FiniteMachine
     # @api public
     def <=>(other)
       other.is_a?(type) &&
-      [name, transition, data] <=> [other.name, other.transition, other.data]
+      [name, from, event_name] <=> [other.name, other.from, other.event_name]
     end
     alias_method :eql?, :==
 

data/lib/finite_machine/logger.rb

@@ -29,13 +29,12 @@ module FiniteMachine
       end
     end
 
-    def report_transition(event_transition, *args)
-      message = "Transition: @event=#{event_transition.name} "
+    def report_transition(name, from, to, *args)
+      message = "Transition: @event=#{name} "
       unless args.empty?
         message << "@with=[#{args.join(',')}] "
       end
-      message << "#{event_transition.from_state} -> "
-      message << "#{event_transition.machine.current}"
+      message << "#{from} -> #{to}"
       info(message)
     end
   end # Logger

data/lib/finite_machine/observer.rb

@@ -1,6 +1,6 @@
 # encoding: utf-8
 
-require 'set'
+require 'finite_machine/hooks'
 
 module FiniteMachine
   # A class responsible for observing state changes
@@ -104,15 +104,22 @@ module FiniteMachine
       on HookEvent::After, *args, &callback.extend(Once)
     end
 
-    # Trigger all listeners
+    # Execute each of the hooks in order with supplied data
+    #
+    # @param [HookEvent] event
+    #   the hook event
+    #
+    # @param [Array[Object]] data
+    #
+    # @return [nil]
     #
     # @api public
-    def trigger(event, *args, &block)
+    def emit(event, *data)
       sync_exclusive do
         [event.type].each do |event_type|
           [event.name, ANY_STATE, ANY_EVENT].each do |event_name|
             hooks.call(event_type, event_name) do |hook|
-              handle_callback(hook, event)
+              handle_callback(hook, event, *data)
               off(event_type, event_name, &hook) if hook.is_a?(Once)
             end
           end
@@ -134,18 +141,26 @@ module FiniteMachine
     #
     # @api private
     def create_callable(hook)
-      deferred_hook = proc do |_trans_event, *_data|
-        machine.instance_exec(_trans_event, *_data, &hook)
+      callback = proc do |trans_event, *data|
+        machine.instance_exec(trans_event, *data, &hook)
       end
-      Callable.new(deferred_hook)
+      Callable.new(callback)
     end
 
     # Handle callback and decide if run synchronously or asynchronously
     #
+    # @param [Proc] :hook
+    #   The hook to evaluate
+    #
+    # @param [HookEvent] :event
+    #   The event for which the hook is called
+    #
+    # @param [Array[Object]] :data
+    #
     # @api private
-    def handle_callback(hook, event)
-      data        = event.data
-      trans_event = TransitionEvent.new(event.transition, *data)
+    def handle_callback(hook, event, *data)
+      to = machine.events_chain.move_to(event.event_name, event.from, *data)
+      trans_event = TransitionEvent.new(event, to)
       callable    = create_callable(hook)
 
       if hook.is_a?(Async)
@@ -155,7 +170,8 @@ module FiniteMachine
         result = callable.call(trans_event, *data)
       end
 
-      event.transition.cancelled = (result == CANCELLED)
+      machine.events_chain.cancel_transitions(event.event_name,
+                                              (result == CANCELLED))
     end
 
     # Callback names including all states and events