finite_machine 0.6.1 → 0.7.0

data/lib/finite_machine/hook_event.rb

@@ -0,0 +1,65 @@
+# encoding: utf-8
+
+module FiniteMachine
+  # A class responsible for event notification
+  class HookEvent
+    include Threadable
+
+    MESSAGE = :trigger
+
+    # HookEvent state
+    attr_threadsafe :state
+
+    # HookEvent type
+    attr_threadsafe :type
+
+    # Data associated with the event
+    attr_threadsafe :data
+
+    # Transition associated with the event
+    attr_threadsafe :transition
+
+    def initialize(state, transition, *data, &block)
+      @state = state
+      @transition = transition
+      @data  = *data
+      @type  = self.class
+    end
+
+    def notify(subscriber, *args, &block)
+      if subscriber.respond_to? MESSAGE
+        subscriber.public_send(MESSAGE, self, *args, &block)
+      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
+
+    def self.event_name
+      name.split('::').last.downcase.to_sym
+    end
+
+    def self.to_s
+      event_name
+    end
+
+    EVENTS.each do |event|
+      (class << self; self; end).class_eval do
+        define_method(event.event_name) { event }
+      end
+    end
+  end # HookEvent
+end # FiniteMachine

data/lib/finite_machine/hooks.rb

@@ -13,7 +13,7 @@ module FiniteMachine
     #   Hoosk.new(machine)
     #
     # @api public
-    def initialize(machine)
+    def initialize
       @collection = Hash.new do |events_hash, event_type|
         events_hash[event_type] = Hash.new do |state_hash, name|
           state_hash[name] = []
@@ -28,13 +28,13 @@ module FiniteMachine
     # @param [Proc]   callback
     #
     # @example
-    #   hooks.register :enterstate, :green do ... end
+    #   hooks.register HookEvent::Enter, :green do ... end
     #
     # @return [Hash]
     #
     # @api public
     def register(event_type, name, callback)
-      @collection[event_type][name] << callback
+      collection[event_type][name] << callback
     end
 
     # Unregister callback
@@ -44,13 +44,14 @@ module FiniteMachine
     # @param [Proc]   callback
     #
     # @example
-    #   hooks.unregister :enterstate, :green do ... end
+    #   hooks.unregister HookEvent::Enter, :green do ... end
     #
     # @return [Hash]
     #
     # @api public
     def unregister(event_type, name, callback)
-      @collection[event_type][name].shift
+      callbacks = collection[event_type][name]
+      callbacks.delete(callback)
     end
 
     # Return all hooks matching event and state
@@ -65,10 +66,37 @@ module FiniteMachine
     # @return [Hash]
     #
     # @api public
-    def call(event_type, event_state, event)
-      @collection[event_type][event_state].each do |hook|
+    def call(event_type, event_state)
+      collection[event_type][event_state].each do |hook|
         yield hook
       end
     end
+
+    # Check if collection has any elements
+    #
+    # @return [Boolean]
+    #
+    # @api public
+    def empty?
+      collection.empty?
+    end
+
+    # String representation
+    #
+    # @return [String]
+    #
+    # @api public
+    def to_s
+      self.inspect
+    end
+
+    # String representation
+    #
+    # @return [String]
+    #
+    # @api public
+    def inspect
+      "<##{self.class}:0x#{object_id.to_s(16)} @collection=#{collection.inspect}>"
+    end
   end # Hooks
 end # FiniteMachine

data/lib/finite_machine/observer.rb

@@ -6,6 +6,7 @@ module FiniteMachine
   # A class responsible for observing state changes
   class Observer
     include Threadable
+    include Safety
 
     # The current state machine
     attr_threadsafe :machine
@@ -19,7 +20,7 @@ module FiniteMachine
     def initialize(machine)
       @machine = machine
       @machine.subscribe(self)
-      @hooks = FiniteMachine::Hooks.new(machine)
+      @hooks = FiniteMachine::Hooks.new
     end
 
     # Evaluate in current context
@@ -31,19 +32,20 @@ module FiniteMachine
 
     # Register callback for a given event type
     #
-    # @param [Symbol, FiniteMachine::Event] event_type
+    # @param [Symbol, FiniteMachine::HookEvent] event_type
     # @param [Array] args
     # @param [Proc]  callback
     #
     # @api public
-    def on(event_type = Event, *args, &callback)
+    # TODO: throw error if event type isn't handled
+    def on(event_type = HookEvent, *args, &callback)
       sync_exclusive do
         name, async, _ = args
         name = ANY_EVENT if name.nil?
         async = false if async.nil?
-        ensure_valid_callback_name!(name)
+        ensure_valid_callback_name!(event_type, name)
         callback.extend(Async) if async == :async
-        hooks.register event_type.to_s, name, callback
+        hooks.register event_type, name, callback
       end
     end
 
@@ -60,39 +62,44 @@ module FiniteMachine
 
     module Async; end
 
-    def listen_on(type, *args, &callback)
-      name   = args.first
-      events = []
-      case name
-      when *state_names then events << :"#{type}state"
-      when *event_names then events << :"#{type}action"
-      else events << :"#{type}state" << :"#{type}action"
-      end
-      events.each { |event| on(Event.send(event), *args, &callback) }
-    end
-
     def on_enter(*args, &callback)
-      listen_on :enter, *args, &callback
+      on HookEvent::Enter, *args, &callback
     end
 
     def on_transition(*args, &callback)
-      listen_on :transition, *args, &callback
+      on HookEvent::Transition, *args, &callback
     end
 
     def on_exit(*args, &callback)
-      listen_on :exit, *args, &callback
+      on HookEvent::Exit, *args, &callback
     end
 
     def once_on_enter(*args, &callback)
-      listen_on :enter, *args, &callback.extend(Once)
+      on HookEvent::Enter, *args, &callback.extend(Once)
     end
 
     def once_on_transition(*args, &callback)
-      listen_on :transition, *args, &callback.extend(Once)
+      on HookEvent::Transition, *args, &callback.extend(Once)
     end
 
     def once_on_exit(*args, &callback)
-      listen_on :exit, *args, &callback.extend(Once)
+      on HookEvent::Exit, *args, &callback.extend(Once)
+    end
+
+    def on_before(*args, &callback)
+      on HookEvent::Before, *args, &callback
+    end
+
+    def on_after(*args, &callback)
+      on HookEvent::After, *args, &callback
+    end
+
+    def once_on_before(*args, &callback)
+      on HookEvent::Before, *args, &callback.extend(Once)
+    end
+
+    def once_on_after(*args, &callback)
+      on HookEvent::After, *args, &callback.extend(Once)
     end
 
     # Trigger all listeners
@@ -101,9 +108,8 @@ module FiniteMachine
     def trigger(event, *args, &block)
       sync_exclusive do
         [event.type, ANY_EVENT].each do |event_type|
-          [event.state, ANY_STATE,
-           ANY_STATE_HOOK, ANY_EVENT_HOOK].each do |event_state|
-            hooks.call(event_type, event_state, event) do |hook|
+          [event.state, ANY_STATE].each do |event_state|
+            hooks.call(event_type, event_state) do |hook|
               handle_callback(hook, event)
               off(event_type, event_state, &hook) if hook.is_a?(Once)
             end
@@ -150,39 +156,14 @@ module FiniteMachine
       event.transition.cancelled = (result == CANCELLED)
     end
 
-    # Set of all state names
+    # Callback names including all states and events
     #
-    # @return [Set]
+    # @return [Array[Symbol]]
+    #   valid callback names
     #
     # @api private
-    def state_names
-      @names = Set.new
-      @names.merge machine.states
-      @names.merge [ANY_STATE, ANY_STATE_HOOK]
-    end
-
-    # Set of all event names
-    #
-    # @return [Set]
-    #
-    # @api private
-    def event_names
-      @names = Set.new
-      @names.merge machine.event_names
-      @names.merge [ANY_EVENT, ANY_EVENT_HOOK]
-    end
-
     def callback_names
-      state_names + event_names
-    end
-
-    def ensure_valid_callback_name!(name)
-      unless callback_names.include?(name)
-        exception = InvalidCallbackNameError
-        machine.catch_error(exception) ||
-        raise(exception, "#{name} is not a valid callback name." +
-        " Valid callback names are #{callback_names.to_a.inspect}")
-      end
+      machine.states + machine.event_names + [ANY_EVENT]
     end
 
     # Forward the message to observer
@@ -196,7 +177,7 @@ module FiniteMachine
     # @api private
     def method_missing(method_name, *args, &block)
       _, event_name, callback_name = *method_name.to_s.match(/^(\w*?on_\w+?)_(\w+)$/)
-      if callback_names.include?(callback_name.to_sym)
+      if callback_name && callback_names.include?(callback_name.to_sym)
         public_send(event_name, :"#{callback_name}", *args, &block)
       else
         super
@@ -214,7 +195,7 @@ module FiniteMachine
     # @api private
     def respond_to_missing?(method_name, include_private = false)
       *_, callback_name = *method_name.to_s.match(/^(\w*?on_\w+?)_(\w+)$/)
-      callback_names.include?(:"#{callback_name}")
+      callback_name && callback_names.include?(:"#{callback_name}")
     end
   end # Observer
 end # FiniteMachine

data/lib/finite_machine/safety.rb

@@ -0,0 +1,113 @@
+# encoding: utf-8
+
+module FiniteMachine
+  # Module for responsible for safety checks against known methods
+  module Safety
+
+    EVENT_CONFLICT_MESSAGE = \
+      "You tried to define an event named \"%{name}\", however this would " \
+      "generate \"%{type}\" method \"%{method}\", which is already defined " \
+      "by %{source}"
+
+    STATE_CALLBACK_CONFLICT_MESSAGE = \
+      "\"%{type}\" callback is a state listener and cannot be used " \
+      "with \"%{name}\" event name. Please use on_before or on_after instead."
+
+    EVENT_CALLBACK_CONFLICT_MESSAGE = \
+      "\"%{type}\" callback is an event listener and cannot be used " \
+      "with \"%{name}\" state name. Please use on_enter, on_transition or " \
+      "on_exit instead."
+
+    CALLBACK_INVALID_MESSAGE = \
+      "\"%{name}\" is not a valid callback name. " \
+      "Valid callback names are \"%{callbacks}"
+
+    # Raise error when the method is already defined
+    #
+    # @example
+    #   detect_event_conflict!(:test, "test=")
+    #
+    # @raise [FiniteMachine::AlreadyDefinedError]
+    #
+    # @return [nil]
+    #
+    # @api public
+    def detect_event_conflict!(event_name, method_name = event_name)
+      if method_already_implemented?(method_name)
+        fail FiniteMachine::AlreadyDefinedError, EVENT_CONFLICT_MESSAGE % {
+          name: event_name,
+          type: :instance,
+          method: method_name,
+          source: 'FiniteMachine'
+        }
+      end
+    end
+
+    # Raise error when the callback name is not valid
+    #
+    # @example
+    #   ensure_valid_callback_name!(HookEvent::Enter, ":state_name")
+    #
+    # @raise [FiniteMachine::InvalidCallbackNameError]
+    #
+    # @return [nil]
+    #
+    # @api public
+    def ensure_valid_callback_name!(event_type, name)
+      message = if machine.states.include?(name) &&
+                   event_type < HookEvent::Anyaction
+        EVENT_CALLBACK_CONFLICT_MESSAGE % {
+          type: "on_#{event_type.to_s}",
+          name: name
+        }
+      elsif machine.event_names.include?(name) &&
+            event_type < HookEvent::Anystate
+        STATE_CALLBACK_CONFLICT_MESSAGE % {
+          type: "on_#{event_type.to_s}",
+          name: name
+        }
+      elsif !callback_names.include?(name)
+        CALLBACK_INVALID_MESSAGE % {
+          name: name,
+          callbacks: callback_names.to_a.inspect
+        }
+      else
+        nil
+      end
+      message && fail_invalid_callback_error(message)
+    end
+
+    private
+
+    def fail_invalid_callback_error(message)
+      exception = InvalidCallbackNameError
+      machine.catch_error(exception) || fail(exception, message)
+    end
+
+    # Check if method is already implemented inside StateMachine
+    #
+    # @param [String] name
+    #   the method name
+    #
+    # @return [Boolean]
+    #
+    # @api private
+    def method_already_implemented?(name)
+      method_defined_within?(name, FiniteMachine::StateMachine)
+    end
+
+    # Check if method is defined within a given class
+    #
+    # @param [String] name
+    #   the method name
+    #
+    # @param [Object] klass
+    #
+    # @return [Boolean]
+    #
+    # @api private
+    def method_defined_within?(name, klass)
+      klass.method_defined?(name) || klass.private_method_defined?(name)
+    end
+  end # Safety
+end # FiniteMachine

data/lib/finite_machine/state_machine.rb

@@ -20,7 +20,7 @@ module FiniteMachine
     attr_threadsafe :state
 
     # Events DSL
-    attr_threadsafe :events
+    attr_threadsafe :events_dsl
 
     # Errors DSL
     attr_threadsafe :errors
@@ -40,23 +40,27 @@ module FiniteMachine
     # The state machine environment
     attr_threadsafe :env
 
+    # The state machine event definitions
+    attr_threadsafe :events_chain
+
     def_delegators :@dsl, :initial, :terminal, :target
 
-    def_delegator :@events, :event
+    def_delegator :@events_dsl, :event
 
     # Initialize state machine
     #
     # @api private
     def initialize(*args, &block)
-      attributes   = args.last.is_a?(Hash) ? args.pop : {}
+      attributes     = args.last.is_a?(Hash) ? args.pop : {}
       @initial_state = DEFAULT_STATE
-      @subscribers = Subscribers.new(self)
-      @events      = EventsDSL.new(self)
-      @errors      = ErrorsDSL.new(self)
-      @observer    = Observer.new(self)
-      @transitions = Hash.new { |hash, name| hash[name] = Hash.new }
-      @env         = Environment.new(target: self)
-      @dsl         = DSL.new(self, attributes)
+      @subscribers   = Subscribers.new(self)
+      @events_dsl    = EventsDSL.new(self)
+      @errors        = ErrorsDSL.new(self)
+      @observer      = Observer.new(self)
+      @transitions   = Hash.new { |hash, name| hash[name] = Hash.new }
+      @events_chain  = {}
+      @env           = Environment.new(target: self)
+      @dsl           = DSL.new(self, attributes)
 
       @dsl.call(&block) if block_given?
     end
@@ -75,9 +79,8 @@ module FiniteMachine
     # @api public
     def notify(event_type, _transition, *data)
       sync_shared do
-        event_class     = Event.const_get(event_type.capitalize.to_s)
-        state_or_action = event_class < Event::Anystate ? state : _transition.name
-        _event          = event_class.new(state_or_action, _transition, *data)
+        state_or_action = event_type < HookEvent::Anystate ? state : _transition.name
+        _event          = event_type.new(state_or_action, _transition, *data)
         subscribers.visit(_event)
       end
     end
@@ -142,7 +145,9 @@ module FiniteMachine
     #
     # @api public
     def states
-      event_names.map { |event| transitions[event].to_a }.flatten.uniq
+      sync_shared do
+        event_names.map { |event| transitions[event].to_a }.flatten.uniq
+      end
     end
 
     # Retireve all event names
@@ -151,7 +156,7 @@ module FiniteMachine
     #
     # @api public
     def event_names
-      transitions.keys
+      sync_shared { transitions.keys }
     end
 
     # Checks if event can be triggered
@@ -191,6 +196,18 @@ module FiniteMachine
       is?(final_state)
     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=#{transitions.inspect}>"
+      end
+    end
+
     private
 
     # Check if state is reachable
@@ -216,32 +233,40 @@ module FiniteMachine
     #
     # @api private
     def transition(_transition, *args, &block)
-      return CANCELLED if valid_state?(_transition)
+      sync_exclusive do
+        notify HookEvent::Before, _transition, *args
 
-      return CANCELLED unless _transition.conditions.all? do |condition|
-                                condition.call(env.target, *args)
-                              end
-      return NOTRANSITION if _transition.different?(state)
+        return CANCELLED if valid_state?(_transition)
+        return CANCELLED unless _transition.valid?(*args, &block)
 
-      sync_exclusive do
-        notify :exitstate, _transition, *args
+        notify HookEvent::Exit, _transition, *args
 
         begin
           _transition.call
-          notify :enteraction, _transition, *args
-          notify :transitionstate, _transition, *args
-          notify :transitionaction, _transition, *args
+
+          notify HookEvent::Transition, _transition, *args
         rescue Exception => e
-          catch_error(e) ||
-            raise(TransitionError, "#(#{e.class}): #{e.message}\n" +
-              "occured at #{e.backtrace.join("\n")}")
+          catch_error(e) || raise_transition_error(e)
         end
 
-        notify :enterstate, _transition, *args
-        notify :exitaction, _transition, *args
+        notify HookEvent::Enter, _transition, *args
+        notify HookEvent::After, _transition, *args
+
+        _transition.same?(state) ? NOTRANSITION : SUCCEEDED
       end
+    end
 
-      SUCCEEDED
+    # Raise when failed to transition between states
+    #
+    # @param [Exception] error
+    #   the error to describe
+    #
+    # @raise [FiniteMachine::TransitionError]
+    #
+    # @api private
+    def raise_transition_error(error)
+      fail(TransitionError, "#(#{error.class}): #{error.message}\n" \
+        "occured at #{error.backtrace.join("\n")}")
     end
 
     # Forward the message to target, observer or self
@@ -254,8 +279,8 @@ module FiniteMachine
     #
     # @api private
     def method_missing(method_name, *args, &block)
-      if env.target.respond_to?(method_name.to_sym)
-        env.target.public_send(method_name.to_sym, *args, &block)
+      if target.respond_to?(method_name.to_sym)
+        target.public_send(method_name.to_sym, *args, &block)
       elsif observer.respond_to?(method_name.to_sym)
         observer.public_send(method_name.to_sym, *args, &block)
       else
@@ -273,7 +298,9 @@ module FiniteMachine
     #
     # @api private
     def respond_to_missing?(method_name, include_private = false)
-      env.target.respond_to?(method_name.to_sym)
+      env.target.respond_to?(method_name.to_sym) ||
+        observer.respond_to?(method_name.to_sym) ||
+        super
     end
   end # StateMachine
 end # FiniteMachine