finite_machine 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b69fcd7446203267dc8130e4c986ea334e4b26ec
-  data.tar.gz: 3a4bca63a58bf4a3c0a509cc99778d66771a535e
+  metadata.gz: 714f488440a58102f64c2c9911b1d55f3f759df5
+  data.tar.gz: 10005291036b23eee4654d2a81eeab01383126da
 SHA512:
-  metadata.gz: d5c2636ea7607b138737e263771b5269d950f1403079e67dfd41d4940241f41cf62d1118cfe7ae177cfe3a716985cad9f33f76313ada9ce4424ba3fcbbd89511
-  data.tar.gz: c40fda5ae25615ca3d2ee239dc59a952596c3860f309c22b8d01e8b4b8acd10f0d7aeb7ddb2f1dc80aecd46c9bd4b3b6e0fd456b28b14dfc9f34144b7ef80fac
+  metadata.gz: a16908a3c0d0c6fceeb196aac75249f5470593020c29658c4b688bbe7af8aa8a2342b8f42cae065ba19167698204061353b27bc12100508ba4bccfe66dcd58bd
+  data.tar.gz: 6aec10fde3d2e76645458a7b60a6aca87784f8193376944b2c0be40c05c4a7ad5facfe75d98c1b155fb9937da504c0a7903a5558caf3e1fd1edd909cfe0341c0

data/CHANGELOG.md

@@ -1,3 +1,14 @@
+0.5.0 (April 28, 2014)
+
+* Change to allow for machine to be constructed as plain object
+* Allow for :initial, :terminal and :target to be machine parameters
+* Add generic Listener interface
+* Change EventQueue to allow for subscription
+* Increase test coverage to 98%
+* Change to allow access to target inside machine dsl
+* Add ability to fire callbacks asynchronously
+* Add initial state storage
+
 0.4.0 (April 13, 2014)
 
 * Change initial state to stop firing event notification

data/README.md

@@ -23,7 +23,7 @@ A minimal finite state machine with a straightforward and intuitive syntax. You
 * ability to check for terminal state
 * conditional transitions
 * sync and async transitions
-* sync and async callbacks (TODO - only sync)
+* sync and async callbacks
 * nested/composable states (TODO)
 
 ## Installation
@@ -70,7 +70,8 @@ Or install it yourself as:
     * [4.7 Fluid callbacks](#47-fluid-callbacks)
     * [4.8 Executing methods inside callbacks](#48-executing-methods-inside-callbacks)
     * [4.9 Defining callbacks](#49-defining-callbacks)
-    * [4.10 Cancelling inside callbacks](#410-cancelling-inside-callbacks)
+    * [4.10 Asynchronous callbacks](#410-asynchronous-callbacks)
+    * [4.11 Cancelling inside callbacks](#411-cancelling-inside-callbacks)
 * [5. Errors](#5-errors)
     * [5.1 Using target](#51-using-target)
 * [6. Integration](#6-integration)
@@ -92,15 +93,27 @@ fm = FiniteMachine.define do
   }
 
   callbacks {
-    on_enter :ready { |event| ... }
-    on_enter :go    { |event| ... }
-    on_enter :stop  { |event| ... }
+    on_enter(:ready) { |event| ... }
+    on_exit(:go)     { |event| ... }
+    on_enter(:stop)  { |event| ... }
   }
 end
 ```
 
 As the example demonstrates, by calling the `define` method on **FiniteMachine** you create an instance of finite state machine. The `events` and `callbacks` scopes help to define the behaviour of the machine. Read [Transitions](#2-transitions) and [Callbacks](#4-callbacks) sections for more details.
 
+Alternatively, you can construct the machine like a regular object without using the DSL. The same machine could be reimplemented as follows:
+
+```ruby
+fm = FiniteMachine.new initial: :red
+fm.event(:ready, :red    => :yellow)
+fm.event(:go,    :yellow => :green)
+fm.event(:stop,  :green  => :red)
+fm.on_enter(:ready) { |event| ... }
+fm.on_exit(:go)     { |event| ... }
+fm.on_enter(:stop)  { |event| ...}
+```
+
 ### 1.1 current
 
 The **FiniteMachine** allows you to query the current state by calling the `current` method.
@@ -144,6 +157,14 @@ end
 fm.current # => :green
 ```
 
+or by passing named argument `:initial` like so
+
+```ruby
+fm = FiniteMachine.define initial: :green do
+  ...
+end
+```
+
 If you want to defer setting the initial state, pass the `:defer` option to the `initial` helper. By default **FiniteMachine** will create `init` event that will allow to transition from `:none` state to the new state.
 
 ```ruby
@@ -280,6 +301,25 @@ end
 
 For more complex example see [Integration](#6-integration) section.
 
+Finally, you can always reference an external context inside the **FiniteMachine** by simply calling `target`, for instance, to reference it inside a callback:
+
+car = Car.new
+
+fm = FiniteMachine.define do
+  initial :neutral
+
+  target car
+
+  events {
+    event :start, :neutral => :one, if: "engine_on?"
+  }
+  callbacks {
+    on_enter_start do |event|
+      target.turn_engine_on
+    end
+  }
+end
+
 ## 2 Transitions
 
 The `events` scope exposes the `event` helper to define possible state transitions.
@@ -687,7 +727,23 @@ fm.on_enter_yellow do |event|
 end
 ```
 
-### 4.10 Cancelling inside callbacks
+### 4.10 Asynchronous callbacks
+
+By default all callbacks are run synchronosuly. In order to add a callback that runs asynchronously, you need to pass second `:async` argument like so:
+
+```ruby
+  on_enter :green, :async do |event| ... end
+```
+
+or
+
+```ruby
+  on_enter_green(:async) { |event| }
+```
+
+This will ensure that when the callback is fired it will run in seperate thread outside of the main execution thread.
+
+### 4.11 Cancelling inside callbacks
 
 Preferred way to handle cancelling transitions is to use [3 Conditional transitions](#3-conditional-transitions). However if the logic is more than one liner you can cancel the event, hence the transition by returning `FiniteMachine::CANCELLED` constant from the callback scope. The two ways you can affect the event are
 

data/lib/finite_machine.rb

@@ -16,10 +16,12 @@ require "finite_machine/event_queue"
 require "finite_machine/hooks"
 require "finite_machine/logger"
 require "finite_machine/transition"
+require "finite_machine/transition_event"
 require "finite_machine/dsl"
 require "finite_machine/state_machine"
 require "finite_machine/subscribers"
 require "finite_machine/observer"
+require "finite_machine/listener"
 
 module FiniteMachine
 
@@ -61,6 +63,9 @@ module FiniteMachine
   # Raised when initial event specified without state name
   MissingInitialStateError = Class.new(::StandardError)
 
+  # Raised when event queue is already dead
+  EventQueueDeadError = Class.new(::StandardError)
+
   Environment = Struct.new(:target)
 
   class << self
@@ -71,8 +76,8 @@ module FiniteMachine
     def define(*args, &block)
       StateMachine.new(*args, &block)
     end
+    alias_method :new, :define
   end
-
 end # FiniteMachine
 
 FiniteMachine.logger = Logger.new(STDERR)

data/lib/finite_machine/catchable.rb

@@ -1,7 +1,6 @@
 # encoding: utf-8
 
 module FiniteMachine
-
   # A mixin to allow for specifying error handlers
   module Catchable
 

data/lib/finite_machine/dsl.rb

@@ -12,7 +12,13 @@ module FiniteMachine
 
     attr_threadsafe :machine
 
-    def initialize(machine)
+    attr_threadsafe :attrs
+
+    # Initialize a generic DSL
+    #
+    # @api public
+    def initialize(machine, attrs = {})
+      self.attrs = attrs
       self.machine = machine
     end
 
@@ -30,6 +36,7 @@ module FiniteMachine
     end
   end # GenericDSL
 
+  # A class responsible for adding state machine specific dsl
   class DSL < GenericDSL
     attr_threadsafe :defer
 
@@ -38,10 +45,12 @@ module FiniteMachine
     # Initialize top level DSL
     #
     # @api public
-    def initialize(machine)
-      super(machine)
+    def initialize(machine, attrs = {})
+      super(machine, attrs)
       machine.state = FiniteMachine::DEFAULT_STATE
-      self.defer = true
+      self.defer    = true
+
+      initialize_attrs
     end
 
     # Define initial state
@@ -59,19 +68,35 @@ module FiniteMachine
     # @api public
     def initial(value)
       state, name, self.defer = parse(value)
-      machine.state = state unless defer
+      unless defer
+        machine.state         = state
+        machine.initial_state = state
+      end
       event = proc { event name, from: FiniteMachine::DEFAULT_STATE, to: state }
       machine.events.call(&event)
     end
 
-    # Attach state machine to an object. This allows state machine
-    # to initiate events in the context of a particular object.
+    # Attach state machine to an object
+    #
+    # This allows state machine to initiate events in the context
+    # of a particular object
+    #
+    # @example
+    #   FiniteMachine.define do
+    #     target :red
+    #  end
     #
     # @param [Object] object
     #
+    # @return [FiniteMachine::StateMachine]
+    #
     # @api public
-    def target(object)
-      machine.env.target = object
+    def target(object = nil)
+      if object.nil?
+        machine.env.target
+      else
+        machine.env.target = object
+      end
     end
 
     # Define terminal state
@@ -79,7 +104,7 @@ module FiniteMachine
     # @example
     #   terminal :red
     #
-    # @return [StateMachine]
+    # @return [FiniteMachine::StateMachine]
     #
     # @api public
     def terminal(value)
@@ -88,6 +113,8 @@ module FiniteMachine
 
     # Define state machine events
     #
+    # @return [FiniteMachine::StateMachine]
+    #
     # @api public
     def events(&block)
       machine.events.call(&block)
@@ -109,6 +136,15 @@ module FiniteMachine
 
     private
 
+    # Initialize state machine properties based off attributes
+    #
+    # @api private
+    def initialize_attrs
+      attrs[:initial]  and initial(attrs[:initial])
+      attrs[:target]   and target(attrs[:target])
+      attrs[:terminal] and terminal(attrs[:terminal])
+    end
+
     # Parse initial options
     #
     # @param [Object] value

data/lib/finite_machine/event.rb

@@ -1,7 +1,6 @@
 # encoding: utf-8
 
 module FiniteMachine
-
   # A class responsible for event notification
   class Event
     include Threadable
@@ -56,11 +55,14 @@ module FiniteMachine
       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.event_name }
+        define_method(event.event_name) { event }
       end
     end
-
   end # Event
 end # FiniteMachine

data/lib/finite_machine/event_queue.rb

@@ -1,11 +1,8 @@
 # encoding: utf-8
 
 module FiniteMachine
-
   # A class responsible for running asynchronous events
   class EventQueue
-    include Enumerable
-
     # Initialize an event queue
     #
     # @example
@@ -13,9 +10,10 @@ module FiniteMachine
     #
     # @api public
     def initialize
-      @queue = Queue.new
-      @mutex = Mutex.new
-      @dead  = false
+      @queue     = Queue.new
+      @mutex     = Mutex.new
+      @dead      = false
+      @listeners = []
 
       @thread = Thread.new do
         process_events
@@ -48,6 +46,16 @@ module FiniteMachine
       ensure
         @mutex.unlock rescue nil
       end
+      self
+    end
+
+    # Add listener to the queue to receive messages
+    #
+    # @api public
+    def subscribe(*args, &block)
+      listener = Listener.new
+      listener.on_delivery(&block)
+      @listeners << listener
     end
 
     # Check if there are any events to handle
@@ -95,31 +103,58 @@ module FiniteMachine
     #
     # @api public
     def shutdown
+      raise EventQueueDeadError, "event queue already dead" if @dead
+
       @mutex.lock
       begin
+        queue = @queue
         @queue.clear
         @dead = true
       ensure
         @mutex.unlock rescue nil
       end
+      while(!queue.empty?)
+        Logger.debug "Discarded message: #{queue.pop}"
+      end
       true
     end
 
+    # Get number of events waiting for processing
+    #
+    # @example
+    #   event_queue.size
+    #
+    # @return [Integer]
+    #
+    # @api public
+    def size
+      @mutex.synchronize { @queue.size }
+    end
+
     private
 
+    # Notify consumers about process event
+    #
+    # @param [FiniteMachine::AsyncCall] event
+    #
+    # @api private
+    def notify_listeners(event)
+      @listeners.each { |listener| listener.handle_delivery(event) }
+    end
+
     # Process all the events
     #
     # @return [Thread]
     #
     # @api private
     def process_events
-      until(@dead) do
+      until @dead
         event = next_event
+        notify_listeners(event)
         event.dispatch
       end
     rescue Exception => ex
       Logger.error "Error while running event: #{ex}"
     end
-
   end # EventQueue
 end # FiniteMachine

data/lib/finite_machine/hooks.rb

@@ -1,7 +1,6 @@
 # encoding: utf-8
 
 module FiniteMachine
-
   # A class reponsible for registering callbacks
   class Hooks
     include Threadable
@@ -71,6 +70,5 @@ module FiniteMachine
         yield hook
       end
     end
-
   end # Hooks
 end # FiniteMachine

data/lib/finite_machine/listener.rb

@@ -0,0 +1,22 @@
+# encoding: utf-8
+
+module FiniteMachine
+  # A generic listener interface
+  class Listener
+    # Define event delivery handler
+    #
+    # @api public
+    def on_delivery(&block)
+      @on_delivery = block
+      self
+    end
+
+    # Invoke event handler
+    #
+    # @api private
+    def call(*args)
+      @on_delivery.call(*args) if @on_delivery
+    end
+    alias_method :handle_delivery, :call
+  end # Listener
+end # FiniteMachine

data/lib/finite_machine/observer.rb

@@ -3,7 +3,6 @@
 require 'set'
 
 module FiniteMachine
-
   # A class responsible for observing state changes
   class Observer
     include Threadable
@@ -30,17 +29,21 @@ module FiniteMachine
       instance_eval(&block)
     end
 
-    # Register callback for a given event
+    # Register callback for a given event type
     #
-    # @param [Symbol] event_type
-    # @param [Symbol] name
-    # @param [Proc]   callback
+    # @param [Symbol, FiniteMachine::Event] event_type
+    # @param [Array] args
+    # @param [Proc]  callback
     #
     # @api public
-    def on(event_type = ANY_EVENT, name = ANY_STATE, &callback)
+    def on(event_type = Event, *args, &callback)
       sync_exclusive do
+        name, async, _ = args
+        name = ANY_EVENT if name.nil?
+        async = false if async.nil?
         ensure_valid_callback_name!(name)
-        hooks.register event_type, name, callback
+        callback.extend(Async) if async == :async
+        hooks.register event_type.to_s, name, callback
       end
     end
 
@@ -55,17 +58,17 @@ module FiniteMachine
 
     module Once; end
 
+    module Async; end
+
     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
-        events << :"#{type}state" << :"#{type}action"
+      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, *args, &callback }
+      events.each { |event| on(Event.send(event), *args, &callback) }
     end
 
     def on_enter(*args, &callback)
@@ -92,37 +95,16 @@ module FiniteMachine
       listen_on :exit, *args, &callback.extend(Once)
     end
 
-    TransitionEvent = Struct.new(:from, :to, :name) do
-      def build(_transition)
-        self.from = _transition.from_state
-        self.to   = _transition.to
-        self.name = _transition.name
-      end
-    end
-
-    # Run callback
+    # Trigger all listeners
     #
-    # @api private
-    def run_callback(hook, event)
-      trans_event = TransitionEvent.new
-      trans_event.build(event.transition)
-      data = event.data
-      transition = event.transition
-      deferred_hook = proc do |_trans_event, *_data|
-        machine.instance_exec(_trans_event, *_data, &hook)
-      end
-      callable = Callable.new(deferred_hook)
-      result = callable.call(trans_event, *data)
-      transition.cancelled = (result == CANCELLED)
-    end
-
+    # @api public
     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)
+              handle_callback(hook, event)
               off(event_type, event_state, &hook) if hook.is_a?(Once)
             end
           end
@@ -132,19 +114,73 @@ module FiniteMachine
 
     private
 
+    # Defer callback execution
+    #
+    # @api private
+    def defer(callable, trans_event, *data)
+      async_call = AsyncCall.build(machine, callable, trans_event, *data)
+      machine.event_queue << async_call
+    end
+
+    # Create callable instance
+    #
+    # @api private
+    def create_callable(hook)
+      deferred_hook = proc do |_trans_event, *_data|
+        machine.instance_exec(_trans_event, *_data, &hook)
+      end
+      Callable.new(deferred_hook)
+    end
+
+    # Handle callback and decide if run synchronously or asynchronously
+    #
+    # @api private
+    def handle_callback(hook, event)
+      trans_event = TransitionEvent.build(event.transition)
+      data        = event.data
+      callable    = create_callable(hook)
+
+      if hook.is_a?(Async)
+        defer(callable, trans_event, *data)
+        result = nil
+      else
+        result = callable.call(trans_event, *data)
+      end
+
+      event.transition.cancelled = (result == CANCELLED)
+    end
+
+    # Set of all state names
+    #
+    # @return [Set]
+    #
+    # @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
-      @callback_names = Set.new
-      @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]
+      state_names + event_names
     end
 
     def ensure_valid_callback_name!(name)
       unless callback_names.include?(name)
         exception = InvalidCallbackNameError
         machine.catch_error(exception) ||
-        raise(InvalidCallbackNameError, "#{name} is not a valid callback name." +
+        raise(exception, "#{name} is not a valid callback name." +
         " Valid callback names are #{callback_names.to_a.inspect}")
       end
     end
@@ -180,6 +216,5 @@ module FiniteMachine
       *_, callback_name = *method_name.to_s.match(/^(\w*?on_\w+?)_(\w+)$/)
       callback_names.include?(:"#{callback_name}")
     end
-
   end # Observer
 end # FiniteMachine

data/lib/finite_machine/state_machine.rb

@@ -1,12 +1,12 @@
 # encoding: utf-8
 
 module FiniteMachine
-
   # Base class for state machine
   class StateMachine
     include Threadable
     include Catchable
     include ThreadContext
+    extend Forwardable
 
     # Initial state, defaults to :none
     attr_threadsafe :initial_state
@@ -38,17 +38,23 @@ module FiniteMachine
     # The state machine environment
     attr_threadsafe :env
 
+    def_delegators :@dsl, :initial, :terminal, :target
+
+    def_delegator :@events, :event
+
     # Initialize state machine
     #
     # @api private
     def initialize(*args, &block)
+      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)
+      @dsl         = DSL.new(self, attributes)
 
       @dsl.call(&block) if block_given?
     end
@@ -268,6 +274,5 @@ module FiniteMachine
     def respond_to_missing?(method_name, include_private = false)
       env.target.respond_to?(method_name.to_sym)
     end
-
   end # StateMachine
 end # FiniteMachine

data/lib/finite_machine/subscribers.rb

@@ -73,6 +73,5 @@ module FiniteMachine
       @subscribers.clear
       self
     end
-
   end # Subscribers
 end # FiniteMachine

data/lib/finite_machine/thread_context.rb

@@ -1,7 +1,6 @@
 # encoding: utf-8
 
 module FiniteMachine
-
   # A mixin to allow sharing of thread context
   module ThreadContext
 

data/lib/finite_machine/threadable.rb

@@ -1,7 +1,6 @@
 # encoding: utf-8
 
 module FiniteMachine
-
   # A mixin to allow instance methods to be synchronized
   module Threadable
     module InstanceMethods
@@ -78,6 +77,5 @@ module FiniteMachine
         end
       end
     end
-
   end # Threadable
 end # FiniteMachine

data/lib/finite_machine/transition.rb

@@ -143,6 +143,7 @@ module FiniteMachine
         transitions     = machine.transitions[name]
         self.from_state = machine.state
         machine.state   = transitions[machine.state] || transitions[ANY_STATE] || name
+        machine.initial_state = machine.state if from_state == DEFAULT_STATE
       end
     end
 

data/lib/finite_machine/transition_event.rb

@@ -0,0 +1,26 @@
+# encoding: utf-8
+
+module FiniteMachine
+  # A class representing a callback transition event
+  class TransitionEvent
+
+    attr_accessor :from
+
+    attr_accessor :to
+
+    attr_accessor :name
+
+    # Build a transition event
+    #
+    # @return [self]
+    #
+    # @api private
+    def self.build(transition)
+      instance = new
+      instance.from = transition.from_state
+      instance.to   = transition.to
+      instance.name = transition.name
+      instance
+    end
+  end # TransitionEvent
+end # FiniteMachine

data/lib/finite_machine/version.rb

@@ -1,5 +1,5 @@
 # encoding: utf-8
 
 module FiniteMachine
-  VERSION = "0.4.0"
+  VERSION = "0.5.0"
 end

data/spec/unit/async_events_spec.rb

@@ -29,10 +29,10 @@ describe FiniteMachine, 'async_events' do
     expect(called).to eql([
       'on_enter_yellow_foo'
     ])
-    fsm.async.stop(:bar)
+    fsm.async(:stop, :bar) # execute directly
     fsm.event_queue.join 0.01
     expect(fsm.current).to eql(:red)
-    expect(called).to eql([
+    expect(called).to match_array([
       'on_enter_yellow_foo',
       'on_enter_red_bar'
     ])
@@ -60,9 +60,39 @@ describe FiniteMachine, 'async_events' do
     bar_thread = Thread.new { fsmBar.async.slow(:bar) }
     [foo_thread, bar_thread].each(&:join)
     [fsmFoo, fsmBar].each { |fsm| fsm.event_queue.join 0.02 }
-    expect(called).to include('(foo)on_enter_yellow_foo')
-    expect(called).to include('(bar)on_enter_yellow_bar')
+    expect(called).to match_array([
+      '(foo)on_enter_yellow_foo',
+      '(bar)on_enter_yellow_bar'
+    ])
     expect(fsmFoo.current).to eql(:yellow)
     expect(fsmBar.current).to eql(:yellow)
   end
+
+  it "permits async callback" do
+    called = []
+    fsm = FiniteMachine.define do
+      initial :green
+
+      events {
+        event :slow,  :green  => :yellow
+        event :go,    :yellow => :green
+      }
+
+      callbacks {
+        on_enter :green,  :async  do |event| called << 'on_enter_green' end
+        on_enter :slow,   :async  do |event| called << 'on_enter_slow'  end
+        on_exit  :yellow, :async  do |event| called << 'on_exit_yellow' end
+        on_exit  :go,     :async  do |event| called << 'on_exit_go'     end
+      }
+    end
+    fsm.slow
+    fsm.go
+    sleep 0.1
+    expect(called).to match_array([
+      'on_enter_green',
+      'on_enter_slow',
+      'on_exit_go',
+      'on_exit_yellow'
+    ])
+  end
 end

data/spec/unit/define_spec.rb

@@ -4,28 +4,51 @@ require 'spec_helper'
 
 describe FiniteMachine, 'define' do
 
-  it "creates system state machine" do
-    fsm = FiniteMachine.define do
-      initial :green
-
-      events {
-        event :slow,  :green  => :yellow
-        event :stop,  :yellow => :red
-        event :ready, :red    => :yellow
-        event :go,    :yellow => :green
-      }
+  context 'with block' do
+    it "creates system state machine" do
+      fsm = FiniteMachine.define do
+        initial :green
+
+        events {
+          event :slow,  :green  => :yellow
+          event :stop,  :yellow => :red
+          event :ready, :red    => :yellow
+          event :go,    :yellow => :green
+        }
+      end
+
+      expect(fsm.current).to eql(:green)
+
+      fsm.slow
+      expect(fsm.current).to eql(:yellow)
+      fsm.stop
+      expect(fsm.current).to eql(:red)
+      fsm.ready
+      expect(fsm.current).to eql(:yellow)
+      fsm.go
+      expect(fsm.current).to eql(:green)
     end
+  end
 
-    expect(fsm.current).to eql(:green)
+  context 'without block' do
+    it "creates state machine" do
+      called = []
+      fsm = FiniteMachine.define
+      fsm.initial(:green)
+      fsm.event(:slow, :green => :yellow)
+      fsm.event(:stop, :yellow => :red)
+      fsm.event(:ready,:red    => :yellow)
+      fsm.event(:go,   :yellow => :green)
+      fsm.on_enter(:yellow) { |event| called << 'on_enter_yellow' }
+      fsm.handle(FiniteMachine::InvalidStateError) { |exception|
+        called << 'error_handler'
+      }
 
-    fsm.slow
-    expect(fsm.current).to eql(:yellow)
-    fsm.stop
-    expect(fsm.current).to eql(:red)
-    fsm.ready
-    expect(fsm.current).to eql(:yellow)
-    fsm.go
-    expect(fsm.current).to eql(:green)
+      expect(fsm.current).to eql(:green)
+      fsm.slow
+      fsm.ready
+      expect(called).to match_array(['on_enter_yellow', 'error_handler'])
+    end
   end
 
   xit "creates multiple machines"

data/spec/unit/event_queue_spec.rb

@@ -0,0 +1,51 @@
+# encoding: utf-8
+
+require 'spec_helper'
+
+describe FiniteMachine::EventQueue do
+
+  subject(:event_queue) { described_class.new }
+
+  it "dispatches all events" do
+    called = []
+    event1 = double(:event1, dispatch: called << 'event1_dispatched')
+    event2 = double(:event2, dispatch: called << 'event2_dispatched')
+    expect(event_queue.size).to be_zero
+    event_queue << event1
+    event_queue << event2
+    sleep 0.001
+    expect(called).to match_array(['event1_dispatched', 'event2_dispatched'])
+  end
+
+  it "logs error" do
+    event = double(:event)
+    expect(FiniteMachine::Logger).to receive(:error)
+    event_queue << event
+    sleep 0.01
+    expect(event_queue).to be_empty
+  end
+
+  it "notifies listeners" do
+    called = []
+    event1 = double(:event1, dispatch: true)
+    event2 = double(:event2, dispatch: true)
+    event3 = double(:event3, dispatch: true)
+    event_queue.subscribe(:listener1) { |event| called << event }
+    event_queue << event1 << event2 << event3
+    sleep 0.01
+    expect(called).to match_array([event1, event2, event3])
+  end
+
+  it "allows to shutdown event queue" do
+    event1 = double(:event1, dispatch: true)
+    event2 = double(:event2, dispatch: true)
+    event3 = double(:event3, dispatch: true)
+    expect(event_queue.alive?).to be_true
+    event_queue << event1
+    event_queue << event2
+    event_queue.shutdown
+    event_queue << event3
+    sleep 0.001
+    expect(event_queue.alive?).to be_false
+  end
+end

data/spec/unit/events_spec.rb

@@ -21,6 +21,17 @@ describe FiniteMachine, 'events' do
     expect(fsm.current).to eql(:red)
   end
 
+  it "allows to add event without events scope" do
+    fsm = FiniteMachine.define do
+      initial :green
+
+      event :slow, :green  => :yellow
+      event :stop, :yellow => :red
+    end
+
+    expect(fsm.current).to eql(:green)
+  end
+
   it "allows for (:from | :to) key pairs to describe transition" do
     fsm = FiniteMachine.define do
       initial :green

data/spec/unit/finished_spec.rb

@@ -27,6 +27,20 @@ describe FiniteMachine, 'finished?' do
     expect(fsm.finished?).to be_true
   end
 
+  it "allows to specify terminal state as parameter" do
+    fsm = FiniteMachine.define terminal: :red do
+      initial :green
+
+      events {
+        event :slow, :green  => :yellow
+        event :stop, :yellow => :red
+      }
+    end
+    fsm.slow
+    fsm.stop
+    expect(fsm.finished?).to be_true
+  end
+
   it "checks without terminal state" do
     fsm = FiniteMachine.define do
       initial :green

data/spec/unit/initialize_spec.rb

@@ -56,6 +56,16 @@ describe FiniteMachine, 'initialize' do
     expect(called).to be_empty
   end
 
+  it "allows to specify initial state through parameter" do
+    fsm = FiniteMachine.define initial: :green do
+      events {
+        event :slow, :green  => :yellow
+        event :stop, :yellow => :red
+      }
+    end
+    expect(fsm.current).to eql(:green)
+  end
+
   it "allows to specify deferred inital state" do
     fsm = FiniteMachine.define do
       initial state: :green, defer: true
@@ -143,4 +153,36 @@ describe FiniteMachine, 'initialize' do
     fsm.b
     expect(fsm.current).to eql(3)
   end
+
+  it "allows to retrieve initial state" do
+    fsm = FiniteMachine.define do
+      initial :green
+
+      events {
+        event :slow, :green  => :yellow
+        event :stop, :yellow => :red
+      }
+    end
+    expect(fsm.current).to eq(:green)
+    expect(fsm.initial_state).to eq(:green)
+    fsm.slow
+    expect(fsm.current).to eq(:yellow)
+    expect(fsm.initial_state).to eq(:green)
+  end
+
+  it "allows to retrieve initial state for deferred" do
+    fsm = FiniteMachine.define do
+      initial state: :green, defer: true
+
+      events {
+        event :slow, :green  => :yellow
+        event :stop, :yellow => :red
+      }
+    end
+    expect(fsm.current).to eq(:none)
+    expect(fsm.initial_state).to eq(:none)
+    fsm.init
+    expect(fsm.current).to eq(:green)
+    expect(fsm.initial_state).to eq(:green)
+  end
 end

data/spec/unit/target_spec.rb

@@ -151,4 +151,27 @@ describe FiniteMachine, '#target' do
       'on_enter_forward with Piotr!'
     ])
   end
+
+  it "allows to access target inside the callback" do
+    context = double(:context)
+    called = nil
+    fsm = FiniteMachine.define do
+      initial :green
+
+      target  context
+
+      events {
+        event :slow, :green  => :yellow
+        event :stop, :yellow => :red
+      }
+      callbacks {
+        on_enter_yellow do |event|
+          called = target
+        end
+      }
+    end
+    expect(fsm.current).to eql(:green)
+    fsm.slow
+    expect(called).to eq(context)
+  end
 end

data/tasks/console.rake

@@ -4,7 +4,7 @@ desc 'Load gem inside irb console'
 task :console do
   require 'irb'
   require 'irb/completion'
-  require File.join(__FILE__, '../lib/finite_machine')
+  require File.join(__FILE__, '../../lib/finite_machine')
   ARGV.clear
   IRB.start
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: finite_machine
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Piotr Murach
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-04-13 00:00:00.000000000 Z
+date: 2014-04-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -55,6 +55,7 @@ files:
 - lib/finite_machine/event.rb
 - lib/finite_machine/event_queue.rb
 - lib/finite_machine/hooks.rb
+- lib/finite_machine/listener.rb
 - lib/finite_machine/logger.rb
 - lib/finite_machine/observer.rb
 - lib/finite_machine/state_machine.rb
@@ -62,6 +63,7 @@ files:
 - lib/finite_machine/thread_context.rb
 - lib/finite_machine/threadable.rb
 - lib/finite_machine/transition.rb
+- lib/finite_machine/transition_event.rb
 - lib/finite_machine/version.rb
 - spec/spec_helper.rb
 - spec/unit/async_events_spec.rb
@@ -69,6 +71,7 @@ files:
 - spec/unit/callbacks_spec.rb
 - spec/unit/can_spec.rb
 - spec/unit/define_spec.rb
+- spec/unit/event_queue_spec.rb
 - spec/unit/events_spec.rb
 - spec/unit/finished_spec.rb
 - spec/unit/handlers_spec.rb
@@ -115,6 +118,7 @@ test_files:
 - spec/unit/callbacks_spec.rb
 - spec/unit/can_spec.rb
 - spec/unit/define_spec.rb
+- spec/unit/event_queue_spec.rb
 - spec/unit/events_spec.rb
 - spec/unit/finished_spec.rb
 - spec/unit/handlers_spec.rb