finite_machine 0.1.0 → 0.2.0

data/finite_machine.gemspec

@@ -8,9 +8,9 @@ Gem::Specification.new do |spec|
   spec.version       = FiniteMachine::VERSION
   spec.authors       = ["Piotr Murach"]
   spec.email         = [""]
-  spec.description   = %q{A minimal finite state machine with a straightforward syntax.}
+  spec.description   = %q{A minimal finite state machine with a straightforward syntax. You can quickly model states, add callbacks and use object-oriented techniques to integrate with ORMs.}
   spec.summary       = %q{A minimal finite state machine with a straightforward syntax.}
-  spec.homepage      = ""
+  spec.homepage      = "https://github.com/peter-murach/finite_machine"
   spec.license       = "MIT"
 
   spec.files         = `git ls-files`.split($/)

data/lib/finite_machine.rb

@@ -6,7 +6,9 @@ require "sync"
 require "finite_machine/version"
 require "finite_machine/threadable"
 require "finite_machine/callable"
+require "finite_machine/catchable"
 require "finite_machine/event"
+require "finite_machine/hooks"
 require "finite_machine/transition"
 require "finite_machine/dsl"
 require "finite_machine/state_machine"
@@ -23,6 +25,10 @@ module FiniteMachine
 
   ANY_EVENT = :any
 
+  ANY_STATE_HOOK = :state
+
+  ANY_EVENT_HOOK = :event
+
   # Returned when transition has successfully performed
   SUCCEEDED = 1
 
@@ -35,11 +41,17 @@ module FiniteMachine
   # When transition between states is invalid
   TransitionError = Class.new(::StandardError)
 
+  # Raised when transitining to invalid state
+  InvalidStateError = Class.new(::ArgumentError)
+
   InvalidEventError = Class.new(::NoMethodError)
 
   # Raised when a callback is defined with invalid name
   InvalidCallbackNameError = Class.new(::StandardError)
 
+  # Raised when event has no transitions
+  NotEnoughTransitionsError = Class.new(::ArgumentError)
+
   Environment = Struct.new(:target)
 
   # TODO: this should instantiate system not the state machine

data/lib/finite_machine/callable.rb

@@ -29,8 +29,7 @@ module FiniteMachine
     # @param [Object] target
     #
     # @api public
-    def call(env, *args, &block)
-      target = env.target
+    def call(target, *args, &block)
       case object
       when Symbol
         target.__send__(@object.to_sym)
@@ -38,11 +37,7 @@ module FiniteMachine
         value = eval "lambda { #{@object} }"
         target.instance_exec(&value)
       when ::Proc
-        if object.arity >= 1
-          object.call(target, *args)
-        else
-          object.call
-        end
+        object.arity.zero? ?  object.call : object.call(target, *args)
       else
         raise ArgumentError, "Unknown callable #{@object}"
       end

data/lib/finite_machine/catchable.rb

@@ -0,0 +1,112 @@
+# encoding: utf-8
+
+module FiniteMachine
+
+  # A mixin to allow for specifying error handlers
+  module Catchable
+
+    def self.included(base)
+      base.class_eval do
+        attr_threadsafe :error_handlers
+      end
+    end
+
+    # Rescue exception raised in state machine
+    #
+    # @param [Array[Exception]] exceptions
+    #
+    # @example
+    #   handle TransitionError, with: :pretty_errors
+    #
+    # @example
+    #   handle TransitionError do |exception|
+    #     logger.info exception.message
+    #     raise exception
+    #   end
+    #
+    # @api public
+    def handle(*exceptions, &block)
+      options = exceptions.last.is_a?(Hash) ? exceptions.pop : {}
+
+      unless options.key?(:with)
+        if block_given?
+          options[:with] = block
+        else
+          raise ArgumentError, 'Need to provide error handler.'
+        end
+      end
+      evaluate_exceptions(exceptions, options)
+    end
+
+    # Catches error and finds a handler
+    #
+    # @param [Exception] exception
+    #
+    # @api public
+    def catch_error(exception)
+      if handler = handler_for_error(exception)
+        handler.arity.zero? ? handler.call : handler.call(exception)
+        true
+      end
+    end
+
+    private
+
+    def handler_for_error(exception)
+      _, handler = error_handlers.reverse.find do |class_name, _|
+        klass = FiniteMachine.const_get(class_name) rescue nil
+        klass ||= extract_const(class_name)
+        exception <= klass
+      end
+      evaluate_handler(handler)
+    end
+
+    # Find constant in state machine namespace
+    #
+    # @param [String] class_name
+    #
+    # @api private
+    def extract_const(class_name)
+      class_name.split('::').reduce(FiniteMachine) do |constant, part|
+        constant.const_get(part)
+      end
+    end
+
+    # Executes given handler
+    #
+    # @api private
+    def evaluate_handler(handler)
+      case handler
+      when Symbol
+        method(handler)
+      when Proc
+        if handler.arity.zero?
+          proc { instance_exec(&handler) }
+        else
+          proc { |_exception| instance_exec(_exception, &handler) }
+        end
+      end
+    end
+
+    # Check if exception inherits from Exception class and add to error handlers
+    #
+    # @param [Array[Exception]] exceptions
+    #
+    # @param [Hash] options
+    #
+    # @api private
+    def evaluate_exceptions(exceptions, options)
+      exceptions.each do |exception|
+        key = if exception.is_a?(Class) && exception <= Exception
+          exception.name
+        elsif exception.is_a?(String)
+          exception
+        else
+          raise ArgumentError, "#{exception} isn't an Exception"
+        end
+
+        error_handlers << [key, options[:with]]
+      end
+    end
+  end # Catchable
+end # FiniteMachine

data/lib/finite_machine/dsl.rb

@@ -2,14 +2,19 @@
 
 module FiniteMachine
 
+  # A generic DSL for describing the state machine
   class GenericDSL
+    include Threadable
+
     class << self
       # @api private
       attr_accessor :top_level
     end
 
+    attr_threadsafe :machine
+
     def initialize(machine)
-      @machine = machine
+      self.machine = machine
     end
 
     def method_missing(method_name, *args, &block)
@@ -21,23 +26,24 @@ module FiniteMachine
     end
 
     def call(&block)
-      instance_eval(&block)
+      sync_exclusive { instance_eval(&block) }
       # top_level.instance_eval(&block)
     end
   end # GenericDSL
 
   class DSL < GenericDSL
 
-    attr_reader :machine
-
-    attr_reader :defer
+    attr_threadsafe :defer
 
-    attr_reader :initial_event
+    attr_threadsafe :initial_event
 
+    # Initialize top level DSL
+    #
+    # @api public
     def initialize(machine)
       super(machine)
       machine.state = FiniteMachine::DEFAULT_STATE
-      @defer = true
+      self.defer = true
     end
 
     # Define initial state
@@ -46,15 +52,8 @@ module FiniteMachine
     #
     # @api public
     def initial(value)
-      if value.is_a?(String) || value.is_a?(Symbol)
-        state, name = value, FiniteMachine::DEFAULT_EVENT_NAME
-        @defer = false
-      else
-        state = value[:state]
-        name  = value.has_key?(:event) ? value[:event] : FiniteMachine::DEFAULT_EVENT_NAME
-        @defer = value[:defer] || true
-      end
-      @initial_event = name
+      state, name, self.defer = parse(value)
+      self.initial_event = name
       event = proc { event name, from: FiniteMachine::DEFAULT_STATE, to: state }
       machine.events.call(&event)
     end
@@ -87,48 +86,64 @@ module FiniteMachine
     # Error handler that throws exception when machine is in illegal state
     #
     # @api public
-    def error
+    def handlers(&block)
+      machine.errors.call(&block)
     end
-  end # DSL
-
-  class EventsDSL < GenericDSL
 
-    attr_reader :machine
+    private
 
-    def initialize(machine)
-      super(machine)
+    # Parse initial options
+    #
+    # @params [String, Hash] value
+    #
+    # @return [Array[Symbol,String]]
+    #
+    # @api private
+    def parse(value)
+      if value.is_a?(String) || value.is_a?(Symbol)
+        [value, FiniteMachine::DEFAULT_EVENT_NAME, false]
+      else
+        [value[:state], value.fetch(:event, FiniteMachine::DEFAULT_EVENT_NAME),
+        !!value[:defer]]
+      end
     end
+  end # DSL
+
+  class EventsDSL < GenericDSL
 
     # Create event and associate transition
     #
+    # @example
+    #   event :go, :green => :yellow
+    #   event :go, :green => :yellow, if: :lights_on?
+    #
+    # @return [Transition]
+    #
     # @api public
     def event(name, attrs = {}, &block)
-      _transition = Transition.new(machine, attrs.merge!(name: name))
-      add_transition(_transition)
-      define_event(_transition)
+      sync_exclusive do
+        _transition = Transition.new(machine, attrs.merge!(name: name))
+        _transition.define
+        _transition.define_event
+      end
     end
+  end # EventsDSL
 
-    # Add transition
-    #
-    # @param [Transition] _transition
-    #
-    # @api private
-    def add_transition(_transition)
-      _transition.from.each do |from|
-        machine.transitions[_transition.name][from] = _transition.to || from
-      end
+  class ErrorsDSL < GenericDSL
+
+    def initialize(machine)
+      super(machine)
+      machine.error_handlers = []
     end
 
-    # Define event
+    # Add error handler
     #
-    # @param [String] name
-    # @param [Transition] _transition
+    # @param [Array] exceptions
     #
-    # @api private
-    def define_event(_transition)
-      machine.class.__send__ :define_method, _transition.name do |*args, &block|
-        transition(_transition, *args, &block)
-      end
+    # @api public
+    def handle(*exceptions, &block)
+      machine.handle(*exceptions, &block)
     end
-  end # EventsDSL
+
+  end # ErrorsDSL
 end # FiniteMachine

data/lib/finite_machine/hooks.rb

@@ -0,0 +1,43 @@
+# encoding: utf-8
+
+module FiniteMachine
+
+  # A class reponsible for registering callbacks
+  class Hooks
+    include Threadable
+
+    attr_threadsafe :collection
+
+    # Initialize a collection of hoooks
+    #
+    # @api public
+    def initialize(machine)
+      @collection = Hash.new do |events_hash, event_type|
+        events_hash[event_type] = Hash.new do |state_hash, name|
+          state_hash[name] = []
+        end
+      end
+    end
+
+    # Register callback
+    #
+    # @param [String] event_type
+    # @param [String] name
+    # @param [Proc]   callback
+    #
+    # @api public
+    def register(event_type, name, callback)
+      @collection[event_type][name] << callback
+    end
+
+    # Return all hooks matching event and state
+    #
+    # @api public
+    def call(event_type, event_state, event)
+      @collection[event_type][event_state].each do |hook|
+        yield hook
+      end
+    end
+
+  end # Hooks
+end # FiniteMachine

data/lib/finite_machine/observer.rb

@@ -18,12 +18,7 @@ module FiniteMachine
     def initialize(machine)
       @machine = machine
       @machine.subscribe(self)
-
-      @hooks = Hash.new { |events_hash, event_type|
-        events_hash[event_type] = Hash.new { |state_hash, name|
-          state_hash[name] = []
-        }
-      }
+      @hooks = FiniteMachine::Hooks.new(machine)
     end
 
     # Evaluate in current context
@@ -41,41 +36,35 @@ module FiniteMachine
     #
     # @api public
     def on(event_type = ANY_EVENT, name = ANY_STATE, &callback)
-      ensure_valid_callback_name!(name)
-      hooks[event_type][name] << callback
+      sync_exclusive do
+        ensure_valid_callback_name!(name)
+        hooks.register event_type, name, callback
+      end
     end
 
-    def on_enter(*args, &callback)
-      if machine.states.any? { |state| state == args.first }
-        on :enterstate, *args, &callback
-      elsif machine.event_names.any? { |name| name == args.first }
-        on :enteraction, *args, &callback
+    def listen_on(type, *args, &callback)
+      name   = args.first
+      events = []
+      if machine.states.include?(name) || name == ANY_STATE_HOOK
+        events << :"#{type}state"
+      elsif machine.event_names.include?(name)  || name == ANY_EVENT_HOOK
+        events << :"#{type}action"
       else
-        on :enterstate, *args, &callback
-        on :enteraction, *args, &callback
+        events << :"#{type}state" << :"#{type}action"
       end
+      events.each { |event| on event, *args, &callback }
+    end
+
+    def on_enter(*args, &callback)
+      listen_on :enter, *args, &callback
     end
 
     def on_transition(*args, &callback)
-      if machine.states.any? { |state| state == args.first }
-        on :transitionstate, *args, &callback
-      elsif machine.event_names.any? { |name| name == args.first }
-        on :transitionaction, *args, &callback
-      else
-        on :transitionstate, *args, &callback
-        on :transitionaction, *args, &callback
-      end
+      listen_on :transition, *args, &callback
     end
 
     def on_exit(*args, &callback)
-      if machine.states.any? { |state| state == args.first }
-        on :exitstate, *args, &callback
-      elsif machine.event_names.any? { |name| name == args.first }
-        on :exitaction, *args, &callback
-      else
-        on :exitstate, *args, &callback
-        on :exitaction, *args, &callback
-      end
+      listen_on :exit, *args, &callback
     end
 
     def method_missing(method_name, *args, &block)
@@ -94,7 +83,7 @@ module FiniteMachine
 
     TransitionEvent = Struct.new(:from, :to, :name) do
       def build(_transition)
-        self.from = _transition.from.first
+        self.from = _transition.from_state
         self.to   = _transition.to
         self.name = _transition.name
       end
@@ -103,14 +92,21 @@ module FiniteMachine
     def run_callback(hook, event)
       trans_event = TransitionEvent.new
       trans_event.build(event.transition)
-      hook.call(trans_event, *event.data)
+      data = event.data
+      deferred_hook = proc { |_trans_event, *_data|
+        machine.instance_exec(_trans_event, *_data, &hook)
+      }
+      deferred_hook.call(trans_event, *data)
     end
 
-    def trigger(event)
-      [event.type, ANY_EVENT].each do |event_type|
-        [event.state, ANY_STATE].each do |event_state|
-          hooks[event_type][event_state].each do |hook|
-            run_callback hook, event
+    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|
+              run_callback(hook, event)
+            end
           end
         end
       end
@@ -123,12 +119,15 @@ module FiniteMachine
       @callback_names.merge machine.event_names
       @callback_names.merge machine.states
       @callback_names.merge [ANY_STATE, ANY_EVENT]
+      @callback_names.merge [ANY_STATE_HOOK, ANY_EVENT_HOOK]
     end
 
     def ensure_valid_callback_name!(name)
       unless callback_names.include?(name)
-        raise InvalidCallbackNameError, "#{name} is not a valid callback name." +
-          " Valid callback names are #{callback_names.to_a.inspect}"
+        exception = InvalidCallbackNameError
+        machine.catch_error(exception) ||
+        raise(InvalidCallbackNameError, "#{name} is not a valid callback name." +
+        " Valid callback names are #{callback_names.to_a.inspect}")
       end
     end