finite_machine 0.0.1 → 0.1.0

data/Rakefile

@@ -1 +1,41 @@
 require "bundler/gem_tasks"
+
+begin
+  require 'rspec/core/rake_task'
+
+  desc 'Run all specs'
+  RSpec::Core::RakeTask.new(:spec) do |task|
+    task.pattern = 'spec/{unit,integration}{,/*/**}/*_spec.rb'
+  end
+
+  namespace :spec do
+    desc 'Run unit specs'
+    RSpec::Core::RakeTask.new(:unit) do |task|
+      task.pattern = 'spec/unit{,/*/**}/*_spec.rb'
+    end
+
+    desc 'Run integration specs'
+    RSpec::Core::RakeTask.new(:integration) do |task|
+      task.pattern = 'spec/integration{,/*/**}/*_spec.rb'
+    end
+  end
+
+rescue LoadError
+  %w[spec spec:unit spec:integration].each do |name|
+    task name do
+      $stderr.puts "In order to run #{name}, do `gem install rspec`"
+    end
+  end
+end
+
+desc 'Run all specs'
+task ci: %w[ spec ]
+
+desc 'Load gem inside irb console'
+task :console do
+  require 'irb'
+  require 'irb/completion'
+  require File.join(__FILE__, '../lib/finite_machine')
+  ARGV.clear
+  IRB.start
+end

data/lib/finite_machine.rb

@@ -1,9 +1,51 @@
+# encoding: utf-8
+
+require "thread"
+require "sync"
+
 require "finite_machine/version"
+require "finite_machine/threadable"
+require "finite_machine/callable"
+require "finite_machine/event"
+require "finite_machine/transition"
+require "finite_machine/dsl"
+require "finite_machine/state_machine"
+require "finite_machine/subscribers"
+require "finite_machine/observer"
 
 module FiniteMachine
 
-  def self.create(&block)
-    StateMachine.new(&block)
+  DEFAULT_STATE = :none
+
+  DEFAULT_EVENT_NAME = :init
+
+  ANY_STATE = :any
+
+  ANY_EVENT = :any
+
+  # Returned when transition has successfully performed
+  SUCCEEDED = 1
+
+  # Returned when transition is cancelled in callback
+  CANCELLED = 2
+
+  # Returned when transition has not changed the state
+  NOTRANSITION = 3
+
+  # When transition between states is invalid
+  TransitionError = Class.new(::StandardError)
+
+  InvalidEventError = Class.new(::NoMethodError)
+
+  # Raised when a callback is defined with invalid name
+  InvalidCallbackNameError = Class.new(::StandardError)
+
+  Environment = Struct.new(:target)
+
+  # TODO: this should instantiate system not the state machine
+  # and then delegate calls to StateMachine instance etc...
+  def self.define(*args, &block)
+    StateMachine.new(*args, &block)
   end
 
 end # FiniteMachine

data/lib/finite_machine/callable.rb

@@ -0,0 +1,51 @@
+# encoding: utf-8
+
+module FiniteMachine
+
+  # A generic interface for executing strings, symbol methods or procs.
+  class Callable
+
+    attr_reader :object
+
+    # Initialize a Callable
+    #
+    # @param [Symbol, String, Proc] object
+    #   the callable object
+    #
+    # @api public
+    def initialize(object)
+      @object = object
+    end
+
+    # Invert callable
+    #
+    # @api public
+    def invert
+      lambda { |*args, &block|  !self.call(*args, &block) }
+    end
+
+    # Execute action
+    #
+    # @param [Object] target
+    #
+    # @api public
+    def call(env, *args, &block)
+      target = env.target
+      case object
+      when Symbol
+        target.__send__(@object.to_sym)
+      when String
+        value = eval "lambda { #{@object} }"
+        target.instance_exec(&value)
+      when ::Proc
+        if object.arity >= 1
+          object.call(target, *args)
+        else
+          object.call
+        end
+      else
+        raise ArgumentError, "Unknown callable #{@object}"
+      end
+    end
+  end # Callable
+end # FiniteMachine

data/lib/finite_machine/dsl.rb

@@ -0,0 +1,134 @@
+# encoding: utf-8
+
+module FiniteMachine
+
+  class GenericDSL
+    class << self
+      # @api private
+      attr_accessor :top_level
+    end
+
+    def initialize(machine)
+      @machine = machine
+    end
+
+    def method_missing(method_name, *args, &block)
+      if @machine.respond_to?(method_name)
+        @machine.send(method_name, *args, &block)
+      else
+        super
+      end
+    end
+
+    def call(&block)
+      instance_eval(&block)
+      # top_level.instance_eval(&block)
+    end
+  end # GenericDSL
+
+  class DSL < GenericDSL
+
+    attr_reader :machine
+
+    attr_reader :defer
+
+    attr_reader :initial_event
+
+    def initialize(machine)
+      super(machine)
+      machine.state = FiniteMachine::DEFAULT_STATE
+      @defer = true
+    end
+
+    # Define initial state
+    #
+    # @params [String, Hash] value
+    #
+    # @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
+      event = proc { event name, from: FiniteMachine::DEFAULT_STATE, to: state }
+      machine.events.call(&event)
+    end
+
+    def target(value)
+      machine.env.target = value
+    end
+
+    # Define terminal state
+    #
+    # @api public
+    def terminal(value)
+      machine.final_state = value
+    end
+
+    # Define state machine events
+    #
+    # @api public
+    def events(&block)
+      machine.events.call(&block)
+    end
+
+    # Define state machine callbacks
+    #
+    # @api public
+    def callbacks(&block)
+      machine.observer.call(&block)
+    end
+
+    # Error handler that throws exception when machine is in illegal state
+    #
+    # @api public
+    def error
+    end
+  end # DSL
+
+  class EventsDSL < GenericDSL
+
+    attr_reader :machine
+
+    def initialize(machine)
+      super(machine)
+    end
+
+    # Create event and associate transition
+    #
+    # @api public
+    def event(name, attrs = {}, &block)
+      _transition = Transition.new(machine, attrs.merge!(name: name))
+      add_transition(_transition)
+      define_event(_transition)
+    end
+
+    # 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
+    end
+
+    # Define event
+    #
+    # @param [String] name
+    # @param [Transition] _transition
+    #
+    # @api private
+    def define_event(_transition)
+      machine.class.__send__ :define_method, _transition.name do |*args, &block|
+        transition(_transition, *args, &block)
+      end
+    end
+  end # EventsDSL
+end # FiniteMachine

data/lib/finite_machine/event.rb

@@ -0,0 +1,66 @@
+# encoding: utf-8
+
+module FiniteMachine
+
+  # A class responsible for event notification
+  class Event
+    include Threadable
+
+    MESSAGE = :trigger
+
+    # Event state
+    attr_threadsafe :state
+
+    # Event 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.event_name
+    end
+
+    def notify(subscriber, *args, &block)
+      if subscriber.respond_to? MESSAGE
+        subscriber.__send__(MESSAGE, self, *args, &block)
+      end
+    end
+
+    class Anystate < Event; end
+
+    class Enterstate < Anystate; end
+
+    class Transitionstate < Anystate; end
+
+    class Exitstate < Anystate; end
+
+    class Anyaction < Event; end
+
+    class Enteraction < Anyaction; end
+
+    class Transitionaction < Anyaction; end
+
+    class Exitaction < Anyaction; end
+
+    EVENTS = Anystate, Enterstate, Transitionstate, Exitstate,
+             Anyaction, Enteraction, Transitionaction, Exitaction
+
+    def self.event_name
+      name.split('::').last.downcase.to_sym
+    end
+
+    EVENTS.each do |event|
+      (class << self; self; end).class_eval do
+        define_method(event.event_name) { event.event_name }
+      end
+    end
+
+  end # Event
+end # FiniteMachine

data/lib/finite_machine/observer.rb

@@ -0,0 +1,136 @@
+# encoding: utf-8
+
+module FiniteMachine
+
+  # A class responsible for observing state changes
+  class Observer
+    include Threadable
+
+    # The current state machine
+    attr_threadsafe :machine
+
+    # The hooks to trigger around the transition lifecycle.
+    attr_threadsafe :hooks
+
+    # Initialize an Observer
+    #
+    # @api public
+    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] = []
+        }
+      }
+    end
+
+    # Evaluate in current context
+    #
+    # @api private
+    def call(&block)
+      instance_eval(&block)
+    end
+
+    # Register callback for a given event.
+    #
+    # @param [Symbol] event_type
+    # @param [Symbol] name
+    # @param [Proc]   callback
+    #
+    # @api public
+    def on(event_type = ANY_EVENT, name = ANY_STATE, &callback)
+      ensure_valid_callback_name!(name)
+      hooks[event_type][name] << callback
+    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
+      else
+        on :enterstate, *args, &callback
+        on :enteraction, *args, &callback
+      end
+    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
+    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
+    end
+
+    def method_missing(method_name, *args, &block)
+      _, event_name, callback_name = *method_name.to_s.match(/^(on_\w+?)_(\w+)$/)
+      if callback_names.include?(callback_name.to_sym)
+        send(event_name, callback_name.to_sym, *args, &block)
+      else
+        super
+      end
+    end
+
+    def respond_to_missing?(method_name, include_private = false)
+      _, callback_name = *method_name.to_s.match(/^(on_\w+?)_(\w+)$/)
+      callback_names.include?(callback_name.to_sym)
+    end
+
+    TransitionEvent = Struct.new(:from, :to, :name) do
+      def build(_transition)
+        self.from = _transition.from.first
+        self.to   = _transition.to
+        self.name = _transition.name
+      end
+    end
+
+    def run_callback(hook, event)
+      trans_event = TransitionEvent.new
+      trans_event.build(event.transition)
+      hook.call(trans_event, *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
+          end
+        end
+      end
+    end
+
+    private
+
+    def callback_names
+      @callback_names = Set.new
+      @callback_names.merge machine.event_names
+      @callback_names.merge machine.states
+      @callback_names.merge [ANY_STATE, ANY_EVENT]
+    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}"
+      end
+    end
+
+  end # Observer
+end # FiniteMachine