finite_machine 0.0.1 → 0.1.0

data/lib/finite_machine/state_machine.rb

@@ -0,0 +1,188 @@
+# encoding: utf-8
+
+module FiniteMachine
+
+  # Base class for state machine
+  class StateMachine
+    include Threadable
+
+    # Initial state, defaults to :none
+    attr_threadsafe :initial_state
+
+    # Final state, defaults to :none
+    attr_threadsafe :final_state
+
+    # Current state
+    attr_threadsafe :state
+
+    # Events DSL
+    attr_threadsafe :events
+
+    # The prefix used to name events.
+    attr_threadsafe :namespace
+
+    # The events and their transitions.
+    attr_threadsafe :transitions
+
+    # The state machine observer
+    attr_threadsafe :observer
+
+    # The state machine subscribers
+    attr_threadsafe :subscribers
+
+    # The state machine environment
+    attr_threadsafe :env
+
+    # Initialize state machine
+    #
+    # @api private
+    def initialize(*args, &block)
+      @subscribers = Subscribers.new(self)
+      @events      = EventsDSL.new(self)
+      @observer    = Observer.new(self)
+      @transitions = Hash.new { |hash, name| hash[name] = Hash.new }
+      @env         = Environment.new(target: self)
+
+      @dsl = DSL.new self
+      @dsl.call(&block) if block_given?
+      send(:"#{@dsl.initial_event}") unless @dsl.defer
+    end
+
+    def subscribe(*observers)
+      @subscribers.subscribe(*observers)
+    end
+
+    # TODO:  use trigger to actually fire state machine events!
+    # Notify about event
+    #
+    # @api public
+    def notify(event_type, _transition, *data)
+      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)
+      subscribers.visit(_event)
+    end
+
+    # Get current state
+    #
+    # @return [String]
+    #
+    # @api public
+    def current
+      state
+    end
+
+    # Check if current state machtes provided state
+    #
+    # @param [String, Array[String]] state
+    #
+    # @return [Boolean]
+    #
+    # @api public
+    def is?(state)
+      if state.is_a?(Array)
+        state.include? current
+      else
+        state == current
+      end
+    end
+
+    # Retrieve all states
+    #
+    # @return [Array[Symbol]]
+    #
+    # @api public
+    def states
+      event_names.map { |event| transitions[event].to_a }.flatten.uniq
+    end
+
+    # Retireve all event names
+    #
+    # @return [Array[Symbol]]
+    #
+    # @api public
+    def event_names
+      transitions.keys
+    end
+
+    # Checks if event can be triggered
+    #
+    # @param [String] event
+    #
+    # @return [Boolean]
+    #
+    # @api public
+    def can?(event)
+      transitions[event].key?(current) || transitions[event].key?(ANY_STATE)
+    end
+
+    # Checks if event cannot be triggered
+    #
+    # @param [String] event
+    #
+    # @return [Boolean]
+    #
+    # @api public
+    def cannot?(event)
+      !can?(event)
+    end
+
+    # Checks if terminal state has been reached
+    #
+    # @return [Boolean]
+    #
+    # @api public
+    def finished?
+      is?(final_state)
+    end
+
+    #
+    #
+    # @api public
+    def errors
+    end
+
+    private
+
+    # Check if state is reachable
+    #
+    # @api private
+    def validate_state(_transition)
+      current_states = transitions[_transition.name].keys
+      if !current_states.include?(state)  && !current_states.include?(ANY_STATE)
+        raise TransitionError, "inappropriate current state '#{state}'"
+      end
+    end
+
+    # Performs transition
+    #
+    # @api private
+    def transition(_transition, *args, &block)
+      validate_state(_transition)
+
+      return CANCELLED unless _transition.conditions.all? { |c| c.call(env) }
+      return NOTRANSITION if state == _transition.to
+
+      sync_exclusive do
+        notify :exitstate, _transition, *args
+        notify :enteraction, _transition, *args
+
+        begin
+          _transition.call
+
+          notify :transitionstate, _transition, *args
+          notify :transitionaction, _transition, *args
+        rescue StandardError => e
+          raise TransitionError, "#(#{e.class}): #{e.message}\n" +
+            "occured at #{e.backtrace.join("\n")}"
+        end
+
+        notify :enterstate, _transition, *args
+        notify :exitaction, _transition, *args
+      end
+
+      SUCCEEDED
+    end
+
+  end # StateMachine
+end # FiniteMachine

data/lib/finite_machine/subscribers.rb

@@ -0,0 +1,41 @@
+# encoding: utf-8
+
+module FiniteMachine
+
+  # A class responsibile for storage of event subscribers
+  class Subscribers
+    include Enumerable
+
+    def initialize(machine)
+      @machine     = machine
+      @subscribers = []
+      @mutex       = Mutex.new
+    end
+
+    def each(&block)
+      @subscribers.each(&block)
+    end
+
+    def index(subscriber)
+      @subscribers.index(subscriber)
+    end
+
+    def empty?
+      @subscribers.empty?
+    end
+
+    def subscribe(*observers)
+      observers.each { |observer| @subscribers << observer }
+    end
+
+    def visit(event)
+      each { |subscriber| @mutex.synchronize { event.notify subscriber } }
+    end
+
+    def reset
+      @subscribers.clear
+      self
+    end
+
+  end # Subscribers
+end # FiniteMachine

data/lib/finite_machine/threadable.rb

@@ -0,0 +1,44 @@
+# encoding: utf-8
+
+module FiniteMachine
+  module Threadable
+    module InstanceMethods
+      @@sync = Sync.new
+
+      def sync_exclusive(&block)
+        @@sync.synchronize(:EX, &block)
+      end
+
+      def sync_shared(&block)
+        @@sync.synchronize(:SH, &block)
+      end
+    end
+
+    def self.included(base)
+      base.extend ClassMethods
+      base.module_eval do
+        include InstanceMethods
+      end
+    end
+
+    module ClassMethods
+      include InstanceMethods
+
+      def attr_threadsafe(*attrs)
+        attrs.flatten.each do |attr|
+          class_eval <<-RUBY_EVAL, __FILE__, __LINE__ + 1
+            def #{attr}
+              sync_shared { @#{attr} }
+            end
+            alias_method '#{attr}?', '#{attr}'
+
+            def #{attr}=(value)
+              sync_exclusive { @#{attr} = value }
+            end
+          RUBY_EVAL
+        end
+      end
+    end
+
+  end # Threadable
+end # FiniteMachine

data/lib/finite_machine/transition.rb

@@ -0,0 +1,69 @@
+# encoding: utf-8
+
+module FiniteMachine
+
+  # Class describing a transition associated with a given event
+  class Transition
+    include Threadable
+
+    attr_threadsafe :name
+
+    # State transitioning from
+    attr_threadsafe :from
+
+    # State transitioning to
+    attr_threadsafe :to
+
+    # Predicates before transitioning
+    attr_threadsafe :conditions
+
+    # The current state machine
+    attr_threadsafe :machine
+
+    # Initialize a Transition
+    #
+    # @api public
+    def initialize(machine, attrs = {})
+      @machine    = machine
+      @name       = attrs.fetch(:name, DEFAULT_STATE)
+      @from, @to  = *parse_states(attrs)
+      @if         = Array(attrs.fetch(:if, []))
+      @unless     = Array(attrs.fetch(:unless, []))
+      @conditions = make_conditions
+    end
+
+    def make_conditions
+      @if.map { |c| Callable.new(c) } +
+        @unless.map { |c| Callable.new(c).invert }
+    end
+
+    # Extract states from attributes
+    #
+    # @api private
+    def parse_states(attrs)
+      _attrs = attrs.dup
+      [:name, :if, :unless].each { |key| _attrs.delete(key) }
+
+      if [:from, :to].any? { |key| attrs.keys.include?(key) }
+        [Array(_attrs[:from] || ANY_STATE), _attrs[:to]]
+      else
+        [(keys = _attrs.keys).flatten, _attrs[keys.first]]
+      end
+    end
+
+    # Execute current transition
+    #
+    # @api private
+    def call
+      sync_exclusive do
+        transitions = machine.transitions[name]
+        machine.state = transitions[machine.state] || transitions[ANY_STATE] || name
+      end
+    end
+
+    def inspect
+      [@name, @from, @to, @conditions].inspect
+    end
+
+  end # Transition
+end # FiniteMachine

data/lib/finite_machine/version.rb

@@ -1,3 +1,5 @@
+# encoding: utf-8
+
 module FiniteMachine
-  VERSION = "0.0.1"
+  VERSION = "0.1.0"
 end

data/spec/spec_helper.rb

@@ -0,0 +1,15 @@
+# encoding: utf-8
+
+require 'finite_machine'
+
+RSpec.configure do |config|
+  config.treat_symbols_as_metadata_keys_with_true_values = true
+  config.run_all_when_everything_filtered = true
+  config.filter_run :focus
+
+  # Run specs in random order to surface order dependencies. If you find an
+  # order dependency and want to debug it, you can fix the order by providing
+  # the seed, which is printed after each run.
+  #     --seed 1234
+  config.order = 'random'
+end

data/spec/unit/callbacks_spec.rb

@@ -0,0 +1,391 @@
+# encoding: utf-8
+
+require 'spec_helper'
+
+describe FiniteMachine, 'callbacks' do
+
+  it "triggers default init event" do
+    called = []
+    fsm = FiniteMachine.define do
+      initial :green
+
+      events {
+        event :slow,  :green  => :yellow
+        event :stop,  :yellow => :red
+        event :ready, :red    => :yellow
+        event :go,    :yellow => :green
+      }
+
+      callbacks {
+        # generic callbacks
+        on_enter      do |event| called << 'on_enter' end
+        on_transition do |event| called << 'on_transition' end
+        on_exit       do |event| called << 'on_exit' end
+
+        # state callbacks
+        on_enter :none  do |event| called << 'on_enter_none' end
+        on_enter :green do |event| called << 'on_enter_green' end
+
+        on_transition :none  do |event| called << 'on_transition_none' end
+        on_transition :green do |event| called << 'on_transition_green' end
+
+        on_exit :none  do |event| called << 'on_exit_none' end
+        on_exit :green do |event| called << 'on_exit_green' end
+
+        # event callbacks
+        on_enter      :init do |event| called << 'on_enter_init' end
+        on_transition :init do |event| called << 'on_transition_init' end
+        on_exit       :init do |event| called << 'on_exit_init' end
+      }
+    end
+
+    expect(called).to eql([
+      'on_exit_none',
+      'on_exit',
+      'on_enter_init',
+      'on_enter',
+      'on_transition_green',
+      'on_transition',
+      'on_transition_init',
+      'on_transition',
+      'on_enter_green',
+      'on_enter',
+      'on_exit_init',
+      'on_exit'
+    ])
+  end
+
+  it "executes callbacks in order" do
+    called = []
+    fsm = FiniteMachine.define do
+      initial :green
+
+      events {
+        event :slow,  :green  => :yellow
+        event :stop,  :yellow => :red
+        event :ready, :red    => :yellow
+        event :go,    :yellow => :green
+      }
+
+      callbacks {
+        # generic callbacks
+        on_enter      do |event| called << 'on_enter' end
+        on_transition do |event| called << 'on_transition' end
+        on_exit       do |event| called << 'on_exit' end
+
+        # state callbacks
+        on_enter :green  do |event| called << 'on_enter_green' end
+        on_enter :yellow do |event| called << "on_enter_yellow" end
+        on_enter :red    do |event| called << "on_enter_red" end
+
+        on_transition :green  do |event| called << 'on_transition_green' end
+        on_transition :yellow do |event| called << "on_transition_yellow" end
+        on_transition :red    do |event| called << "on_transition_red" end
+
+        on_exit :green  do |event| called << 'on_exit_green' end
+        on_exit :yellow do |event| called << "on_exit_yellow" end
+        on_exit :red    do |event| called << "on_exit_red" end
+
+        # event callbacks
+        on_enter :slow  do |event| called << 'on_enter_slow' end
+        on_enter :stop  do |event| called << "on_enter_stop" end
+        on_enter :ready do |event| called << "on_enter_ready" end
+        on_enter :go    do |event| called << "on_enter_go" end
+
+        on_transition :slow  do |event| called << 'on_transition_slow' end
+        on_transition :stop  do |event| called << "on_transition_stop" end
+        on_transition :ready do |event| called << "on_transition_ready" end
+        on_transition :go    do |event| called << "on_transition_go" end
+
+        on_exit :slow  do |event| called << 'on_exit_slow' end
+        on_exit :stop  do |event| called << "on_exit_stop" end
+        on_exit :ready do |event| called << "on_exit_ready" end
+        on_exit :go    do |event| called << "on_exit_go" end
+      }
+    end
+
+    called = []
+    fsm.slow
+    expect(called).to eql([
+      'on_exit_green',
+      'on_exit',
+      'on_enter_slow',
+      'on_enter',
+      'on_transition_yellow',
+      'on_transition',
+      'on_transition_slow',
+      'on_transition',
+      'on_enter_yellow',
+      'on_enter',
+      'on_exit_slow',
+      'on_exit'
+    ])
+
+    called = []
+    fsm.stop
+    expect(called).to eql([
+      'on_exit_yellow',
+      'on_exit',
+      'on_enter_stop',
+      'on_enter',
+      'on_transition_red',
+      'on_transition',
+      'on_transition_stop',
+      'on_transition',
+      'on_enter_red',
+      'on_enter',
+      'on_exit_stop',
+      'on_exit'
+    ])
+
+    called = []
+    fsm.ready
+    expect(called).to eql([
+      'on_exit_red',
+      'on_exit',
+      'on_enter_ready',
+      'on_enter',
+      'on_transition_yellow',
+      'on_transition',
+      'on_transition_ready',
+      'on_transition',
+      'on_enter_yellow',
+      'on_enter',
+      'on_exit_ready',
+      'on_exit'
+    ])
+
+    called = []
+    fsm.go
+    expect(called).to eql([
+      'on_exit_yellow',
+      'on_exit',
+      'on_enter_go',
+      'on_enter',
+      'on_transition_green',
+      'on_transition',
+      'on_transition_go',
+      'on_transition',
+      'on_enter_green',
+      'on_enter',
+      'on_exit_go',
+      'on_exit'
+    ])
+  end
+
+  it "allows multiple callbacks for the same state" do
+    called = []
+    fsm = FiniteMachine.define do
+      initial :green
+
+      events {
+        event :slow,  :green  => :yellow
+        event :stop,  :yellow => :red
+        event :ready, :red    => :yellow
+        event :go,    :yellow => :green
+      }
+
+      callbacks {
+        # generic callbacks
+        on_enter      do |event| called << 'on_enter' end
+        on_transition do |event| called << 'on_transition' end
+        on_exit       do |event| called << 'on_exit' end
+
+        # state callbacks
+        on_exit :green do |event| called << 'on_exit_green_1' end
+        on_exit :green do |event| called << 'on_exit_green_2' end
+        on_enter :yellow do |event| called << 'on_enter_yellow_1' end
+        on_enter :yellow do |event| called << 'on_enter_yellow_2' end
+        on_transition :yellow do |event| called << 'on_transition_yellow_1' end
+        on_transition :yellow do |event| called << 'on_transition_yellow_2' end
+
+        # event callbacks
+        on_enter      :slow do |event| called << 'on_enter_slow_1' end
+        on_enter      :slow do |event| called << 'on_enter_slow_2' end
+        on_transition :slow do |event| called << 'on_transition_slow_1' end
+        on_transition :slow do |event| called << 'on_transition_slow_2' end
+        on_exit       :slow do |event| called << 'on_exit_slow_1' end
+        on_exit       :slow do |event| called << 'on_exit_slow_2' end
+      }
+    end
+
+    called = []
+    fsm.slow
+    expect(fsm.current).to eql(:yellow)
+    expect(called).to eql([
+      'on_exit_green_1',
+      'on_exit_green_2',
+      'on_exit',
+      'on_enter_slow_1',
+      'on_enter_slow_2',
+      'on_enter',
+      'on_transition_yellow_1',
+      'on_transition_yellow_2',
+      'on_transition',
+      'on_transition_slow_1',
+      'on_transition_slow_2',
+      'on_transition',
+      'on_enter_yellow_1',
+      'on_enter_yellow_2',
+      'on_enter',
+      'on_exit_slow_1',
+      'on_exit_slow_2',
+      'on_exit'
+    ])
+  end
+
+  it "allows for fluid callback definition" do
+    called = []
+    fsm = FiniteMachine.define do
+      initial :green
+
+      events {
+        event :slow,  :green  => :yellow
+        event :stop,  :yellow => :red
+        event :ready, :red    => :yellow
+        event :go,    :yellow => :green
+      }
+
+      callbacks {
+        # state callbacks
+        on_exit_green do |event| called << 'on_exit_green' end
+        on_enter_yellow do |event| called << 'on_enter_yellow' end
+        on_transition_yellow do |event| called << 'on_transition_yellow' end
+
+        # event callbacks
+        on_enter_slow do |event| called << 'on_enter_slow' end
+        on_transition_slow do |event| called << 'on_transition_slow' end
+        on_exit_slow do |event| called << 'on_exit_slow' end
+      }
+    end
+
+    called = []
+    fsm.slow
+    expect(fsm.current).to eql(:yellow)
+    expect(called).to eql([
+      'on_exit_green',
+      'on_enter_slow',
+      'on_transition_yellow',
+      'on_transition_slow',
+      'on_enter_yellow',
+      'on_exit_slow'
+    ])
+  end
+
+  it "passes event object to callback" do
+    evt = nil
+
+    fsm = FiniteMachine.define do
+      initial :green
+
+      events {
+        event :slow,  :green  => :yellow
+      }
+
+      callbacks {
+        on_enter(:yellow) { |e| evt = e }
+      }
+    end
+
+    expect(fsm.current).to eql(:green)
+    fsm.slow
+    expect(fsm.current).to eql(:yellow)
+
+    expect(evt.from).to eql(:green)
+    expect(evt.to).to eql(:yellow)
+    expect(evt.name).to eql(:slow)
+  end
+
+  it "passes extra parameters to callbacks" do
+    expected = {name: :init, from: :none, to: :green, a: nil, b: nil, c: nil }
+
+    callback = Proc.new { |event, a, b, c|
+      expect(event.from).to eql(expected[:from])
+      expect(event.to).to eql(expected[:to])
+      expect(event.name).to eql(expected[:name])
+      expect(a).to eql(expected[:a])
+      expect(b).to eql(expected[:b])
+      expect(c).to eql(expected[:c])
+    }
+
+    fsm = FiniteMachine.define do
+      initial :green
+
+      events {
+        event :slow,  :green  => :yellow
+        event :stop,  :yellow => :red
+        event :ready, :red    => :yellow
+        event :go,    :yellow => :green
+      }
+
+      callbacks {
+        # generic callbacks
+        on_enter      &callback
+        on_transition &callback
+        on_exit       &callback
+
+        # state callbacks
+        on_enter :green,  &callback
+        on_enter :yellow, &callback
+        on_enter :red,    &callback
+
+        on_transition :green , &callback
+        on_transition :yellow, &callback
+        on_transition :red   , &callback
+
+        on_exit :green , &callback
+        on_exit :yellow, &callback
+        on_exit :red   , &callback
+
+        # event callbacks
+        on_enter :slow , &callback
+        on_enter :stop , &callback
+        on_enter :ready, &callback
+        on_enter :go   , &callback
+
+        on_transition :slow , &callback
+        on_transition :stop , &callback
+        on_transition :ready, &callback
+        on_transition :go   , &callback
+
+        on_exit :slow , &callback
+        on_exit :stop , &callback
+        on_exit :ready, &callback
+        on_exit :go   , &callback
+      }
+    end
+
+
+    expected = {name: :slow, from: :green, to: :yellow, a: 1, b: 2, c: 3}
+    fsm.slow(1, 2, 3)
+
+    expected = {name: :stop, from: :yellow, to: :red, a: 'foo', b: 'bar'}
+    fsm.stop('foo', 'bar')
+
+    expected = {name: :ready, from: :red, to: :yellow, a: :foo, b: :bar}
+    fsm.ready(:foo, :bar)
+
+    expected = {name: :go, from: :yellow, to: :green, a: nil, b: nil}
+    fsm.go(nil, nil)
+  end
+
+  it "raises an error with invalid callback name" do
+    expect {
+      FiniteMachine.define do
+        initial :green
+
+        events {
+          event :slow,  :green  => :yellow
+        }
+
+        callbacks {
+          on_enter(:magic) { |event| called << 'on_enter'}
+        }
+      end
+    }.to raise_error(FiniteMachine::InvalidCallbackNameError, /magic is not a valid callback name/)
+  end
+
+  xit "propagates exceptions raised inside callback"
+
+  xit "executes callbacks with multiple 'from' transitions"
+end