finite_machine 0.8.1 → 0.9.0

data/lib/finite_machine/dsl.rb

@@ -55,19 +55,38 @@ module FiniteMachine
 
     # Define initial state
     #
+    # @param [Symbol] value
+    #   The initial state name.
+    # @param [Hash[Symbol]] options
+    # @option options [Symbol] :event
+    #   The event name.
+    # @option options [Symbol] :defer
+    #   Set to true to defer initial state transition.
+    #   Default false.
+    # @option options [Symbol] :silent
+    #   Set to true to disable callbacks.
+    #   Default true.
+    #
     # @example
     #   initial :green
     #
-    # @example
+    # @example Defer initial event
     #   initial state: green, defer: true
     #
+    # @example Trigger callbacks
+    #   initial :green, silent: false
+    #
+    # @example Redefine event name
+    #   initial :green, event: :start
+    #
     # @param [String, Hash] value
     #
     # @return [StateMachine]
     #
     # @api public
-    def initial(value)
-      state, name, self.defer, silent = parse(value)
+    def initial(value, options = {})
+      state = (value && !value.is_a?(Hash)) ? value : raise_missing_state
+      name, self.defer, silent = parse(options)
       self.initial_event = name
       machine.event(name, FiniteMachine::DEFAULT_STATE => state, silent: silent)
     end
@@ -112,12 +131,17 @@ module FiniteMachine
     # @return [FiniteMachine::StateMachine]
     #
     # @api public
-    def terminal(value)
-      machine.final_state = value
+    def terminal(*values)
+      machine.final_state = values
     end
 
     # Define state machine events
     #
+    # @example
+    #   events do
+    #     event :start, :red => :green
+    #   end
+    #
     # @return [FiniteMachine::StateMachine]
     #
     # @api public
@@ -127,6 +151,13 @@ module FiniteMachine
 
     # Define state machine callbacks
     #
+    # @example
+    #   callbacks do
+    #     on_enter :green do |event| ... end
+    #   end
+    #
+    # @return [FiniteMachine::Observer]
+    #
     # @api public
     def callbacks(&block)
       machine.observer.call(&block)
@@ -159,21 +190,25 @@ module FiniteMachine
     # @api private
     def parse(value)
       if value.is_a?(Hash)
-        [value.fetch(:state) { raise_missing_state },
-         value.fetch(:event) { FiniteMachine::DEFAULT_EVENT_NAME },
+        [value.fetch(:event) { FiniteMachine::DEFAULT_EVENT_NAME },
          value.fetch(:defer) { false },
          value.fetch(:silent) { true }]
       else
-        [value, FiniteMachine::DEFAULT_EVENT_NAME, false, true]
+        [FiniteMachine::DEFAULT_EVENT_NAME, false, true]
       end
     end
 
     # Raises missing state error
     #
+    # @raise [MissingInitialStateError]
+    #   Raised when state name is not provided for initial.
+    #
+    # @return [nil]
+    #
     # @api private
     def raise_missing_state
-      raise MissingInitialStateError,
-            'Provide state to transition :to for the initial event'
+      fail MissingInitialStateError,
+           'Provide state to transition :to for the initial event'
     end
   end # DSL
 

data/lib/finite_machine/event.rb

@@ -3,6 +3,7 @@
 module FiniteMachine
   # A class representing event with transitions
   class Event
+    include Comparable
     include Threadable
 
     # The name of this event
@@ -26,8 +27,11 @@ module FiniteMachine
       @silent  = attrs.fetch(:silent, false)
       @state_transitions = []
       # TODO: add event conditions
+      freeze
     end
 
+    protected :machine
+
     # Add transition for this event
     #
     # @param [FiniteMachine::Transition] transition
@@ -109,7 +113,19 @@ module FiniteMachine
     #
     # @api public
     def inspect
-      "<##{self.class} @name=#{@name}, @transitions=#{state_transitions.inspect}>"
+      "<##{self.class} @name=#{name}, @silent=#{silent}, " \
+      "@transitions=#{state_transitions.inspect}>"
+    end
+
+    # Compare whether the instance is greater, less then or equal to other
+    #
+    # @return [-1 0 1]
+    #
+    # @api public
+    def <=>(other)
+      other.is_a?(self.class) && [name, silent, state_transitions] <=>
+        [other.name, other.silent, other.state_transitions]
     end
+    alias_method :eql?, :==
   end # Event
 end # FiniteMachine

data/lib/finite_machine/hook_event.rb

@@ -4,11 +4,12 @@ module FiniteMachine
   # A class responsible for event notification
   class HookEvent
     include Threadable
+    include Comparable
 
     MESSAGE = :trigger
 
-    # HookEvent state
-    attr_threadsafe :state
+    # HookEvent name
+    attr_threadsafe :name
 
     # HookEvent type
     attr_threadsafe :type
@@ -19,13 +20,50 @@ module FiniteMachine
     # Transition associated with the event
     attr_threadsafe :transition
 
-    def initialize(state, transition, *data, &block)
-      @state = state
+    # Instantiate a new HookEvent object
+    #
+    # @param [Symbol] name
+    #   The action or state name
+    # @param [FiniteMachine::Transition]
+    #   The transition associated with this event.
+    # @param [Array[Object]] data
+    #
+    # @example
+    #   HookEvent.new(:green, ...)
+    #
+    # @return [Object]
+    #
+    # @api public
+    def initialize(name, transition, *data)
+      @name       = name
       @transition = transition
-      @data  = *data
-      @type  = self.class
+      @data       = *data
+      @type       = self.class
+      freeze
     end
 
+    # Build event hook
+    #
+    # @param [Symbol] :state
+    #   The state name.
+    # @param [FiniteMachine::Transition] :event_transition
+    #   The transition associted with this hook.
+    # @param [Array[Object]] :data
+    #   The data associated with this hook
+    #
+    # @return [self]
+    #
+    # @api public
+    def self.build(state, event_transition, *data)
+      state_or_action = self < Anystate ? state : event_transition.name
+      new(state_or_action, event_transition, *data)
+    end
+
+    # Notify subscriber about this event
+    #
+    # @return [nil]
+    #
+    # @api public
     def notify(subscriber, *args, &block)
       if subscriber.respond_to? MESSAGE
         subscriber.public_send(MESSAGE, self, *args, &block)
@@ -48,13 +86,34 @@ module FiniteMachine
 
     EVENTS = Anystate, Enter, Transition, Exit, Anyaction, Before, After
 
+    # Extract event name
+    #
+    # @return [String] the event name
+    #
+    # @api public
     def self.event_name
       name.split('::').last.downcase.to_sym
     end
 
+    # String representation
+    #
+    # @return [String] the event name
+    #
+    # @api public
     def self.to_s
-      event_name
+      event_name.to_s
+    end
+
+    # Compare whether the instance is greater, less then or equal to other
+    #
+    # @return [-1 0 1]
+    #
+    # @api public
+    def <=>(other)
+      other.is_a?(type) &&
+      [name, transition, data] <=> [other.name, other.transition, other.data]
     end
+    alias_method :eql?, :==
 
     EVENTS.each do |event|
       (class << self; self; end).class_eval do

data/lib/finite_machine/observer.rb

@@ -108,10 +108,10 @@ module FiniteMachine
     def trigger(event, *args, &block)
       sync_exclusive do
         [event.type, ANY_EVENT].each do |event_type|
-          [event.state, ANY_STATE].each do |event_state|
-            hooks.call(event_type, event_state) do |hook|
+          [event.name, ANY_STATE].each do |event_name|
+            hooks.call(event_type, event_name) do |hook|
               handle_callback(hook, event)
-              off(event_type, event_state, &hook) if hook.is_a?(Once)
+              off(event_type, event_name, &hook) if hook.is_a?(Once)
             end
           end
         end

data/lib/finite_machine/state_machine.rb

@@ -75,14 +75,22 @@ module FiniteMachine
     end
 
     # TODO:  use trigger to actually fire state machine events!
-    # Notify about event
+    # Notify about event all the subscribers
+    #
+    # @param [FiniteMachine::HookEvent] :event_type
+    #   The hook event type.
+    # @param [FiniteMachine::Transition] :event_transition
+    #   The event transition.
+    # @param [Array[Object]] :data
+    #   The data associated with the hook event.
+    #
+    # @return [nil]
     #
     # @api public
-    def notify(event_type, _transition, *data)
+    def notify(event_type, event_transition, *data)
       sync_shared do
-        state_or_action = event_type < HookEvent::Anystate ? state : _transition.name
-        _event          = event_type.new(state_or_action, _transition, *data)
-        subscribers.visit(_event)
+        hook_event = event_type.build(state, event_transition, *data)
+        subscribers.visit(hook_event)
       end
     end
 
@@ -177,7 +185,7 @@ module FiniteMachine
       event       = args.shift
       valid_state = transitions[event].key?(current)
       valid_state ||= transitions[event].key?(ANY_STATE)
-      valid_state &&= events_chain.valid_event?(event, *args, &block)
+      valid_state && events_chain.valid_event?(event, *args, &block)
     end
 
     # Checks if event cannot be triggered
@@ -199,7 +207,7 @@ module FiniteMachine
     # @return [Boolean]
     #
     # @api public
-    def finished?
+    def terminated?
       is?(final_state)
     end
 
@@ -230,47 +238,51 @@ module FiniteMachine
 
     # Check if state is reachable
     #
+    # @param [FiniteMachine::Transition]
+    #
+    # @return [Boolean]
+    #
     # @api private
-    def valid_state?(_transition)
-      current_states = transitions[_transition.name].keys
+    def valid_state?(event_transition)
+      current_states = transitions[event_transition.name].keys
       if !current_states.include?(state) && !current_states.include?(ANY_STATE)
         exception = InvalidStateError
         catch_error(exception) ||
-          raise(exception, "inappropriate current state '#{state}'")
+          fail(exception, "inappropriate current state '#{state}'")
         true
       end
     end
 
     # Performs transition
     #
-    # @param [Transition] _transition
+    # @param [Transition] event_transition
     # @param [Array] args
     #
     # @return [Integer]
     #   the status code for the transition
     #
     # @api private
-    def transition(_transition, *args, &block)
+    def transition(event_transition, *args, &block)
       sync_exclusive do
-        notify HookEvent::Before, _transition, *args
+        notify HookEvent::Before, event_transition, *args
 
-        return CANCELLED if valid_state?(_transition)
-        return CANCELLED unless _transition.valid?(*args, &block)
+        return CANCELLED if valid_state?(event_transition)
+        return CANCELLED unless event_transition.valid?(*args, &block)
 
-        notify HookEvent::Exit, _transition, *args
+        notify HookEvent::Exit, event_transition, *args
 
         begin
-          _transition.call(*args)
+          event_transition.call(*args)
 
-          notify HookEvent::Transition, _transition, *args
+          notify HookEvent::Transition, event_transition, *args
         rescue Exception => e
           catch_error(e) || raise_transition_error(e)
         end
 
-        notify HookEvent::Enter, _transition, *args
-        notify HookEvent::After, _transition, *args
+        notify HookEvent::Enter, event_transition, *args
+        notify HookEvent::After, event_transition, *args
 
-        _transition.same?(state) ? NOTRANSITION : SUCCEEDED
+        event_transition.same?(state) ? NOTRANSITION : SUCCEEDED
       end
     end
 
@@ -287,7 +299,7 @@ module FiniteMachine
         "occured at #{error.backtrace.join("\n")}")
     end
 
-    # Forward the message to target, observer or self
+    # Forward the message to observer or self
     #
     # @param [String] method_name
     #
@@ -297,9 +309,7 @@ module FiniteMachine
     #
     # @api private
     def method_missing(method_name, *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)
+      if observer.respond_to?(method_name.to_sym)
         observer.public_send(method_name.to_sym, *args, &block)
       else
         super
@@ -316,9 +326,7 @@ module FiniteMachine
     #
     # @api private
     def respond_to_missing?(method_name, include_private = false)
-      env.target.respond_to?(method_name.to_sym) ||
-        observer.respond_to?(method_name.to_sym) ||
-        super
+      observer.respond_to?(method_name.to_sym) || super
     end
   end # StateMachine
 end # FiniteMachine

data/lib/finite_machine/version.rb

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

data/spec/spec_helper.rb

@@ -18,9 +18,9 @@ end
 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
+  config.raise_errors_for_deprecations!
 
   # 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
@@ -30,7 +30,7 @@ RSpec.configure do |config|
 
   # Remove defined constants
   config.before :each do
-    [:Car, :Logger, :Bug, :User].each do |class_name|
+    [:Car, :Logger, :Bug, :User, :Engine].each do |class_name|
       if Object.const_defined?(class_name)
         Object.send(:remove_const, class_name)
       end

data/spec/unit/async_events_spec.rb

@@ -71,7 +71,7 @@ describe FiniteMachine, 'async_events' do
   it "permits async callback" do
     called = []
     fsm = FiniteMachine.define do
-      initial state: :green, silent: false
+      initial :green, silent: false
 
       events {
         event :slow,  :green  => :yellow

data/spec/unit/callbacks_spec.rb

@@ -7,7 +7,7 @@ describe FiniteMachine, 'callbacks' do
   it "triggers default init event" do
     called = []
     fsm = FiniteMachine.define do
-      initial state: :green, defer: true, silent: false
+      initial :green, defer: true, silent: false
 
       callbacks {
         # generic state callbacks
@@ -54,7 +54,7 @@ describe FiniteMachine, 'callbacks' do
   it "executes callbacks in order" do
     called = []
     fsm = FiniteMachine.define do
-      initial state: :green, silent: false
+      initial :green, silent: false
 
       events {
         event :slow,  :green  => :yellow
@@ -173,7 +173,7 @@ describe FiniteMachine, 'callbacks' do
   it "maintains transition execution sequence from UML statechart" do
     called = []
     fsm = FiniteMachine.define do
-      initial state: :previous, silent: false
+      initial :previous, silent: false
 
       events {
         event :go, :previous => :next, if: -> { called << 'guard'; true}
@@ -207,7 +207,7 @@ describe FiniteMachine, 'callbacks' do
   it "allows multiple callbacks for the same state" do
     called = []
     fsm = FiniteMachine.define do
-      initial state: :green, silent: false
+      initial :green, silent: false
 
       events {
         event :slow,  :green  => :yellow
@@ -359,12 +359,12 @@ describe FiniteMachine, '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])
+      target.expect(event.from).to target.eql(expected[:from])
+      target.expect(event.to).to target.eql(expected[:to])
+      target.expect(event.name).to target.eql(expected[:name])
+      target.expect(a).to target.eql(expected[:a])
+      target.expect(b).to target.eql(expected[:b])
+      target.expect(c).to target.eql(expected[:c])
     }
     context = self
 
@@ -435,7 +435,7 @@ describe FiniteMachine, 'callbacks' do
         initial :green
 
         events {
-          event :slow,  :green  => :yellow
+          event :slow, :green => :yellow
         }
 
         callbacks {
@@ -458,7 +458,7 @@ describe FiniteMachine, 'callbacks' do
   it "doesn't allow to mix event callback with state name" do
     expect {
       FiniteMachine.define do
-        events { event :slow,  :green  => :yellow }
+        events { event :slow, :green => :yellow }
 
         callbacks { on_before_green do |event| end }
       end
@@ -469,7 +469,7 @@ describe FiniteMachine, 'callbacks' do
     fsm = FiniteMachine.define do
       initial :green
 
-      events { event :slow,  :green  => :yellow }
+      events { event :slow, :green => :yellow }
 
       callbacks { on_enter(:yellow) { raise RuntimeError } }
     end
@@ -549,11 +549,11 @@ describe FiniteMachine, 'callbacks' do
   it "triggers callbacks only once" do
     called = []
     fsm = FiniteMachine.define do
-      initial state: :green, silent: false
+      initial :green, silent: false
 
       events {
-        event :slow,  :green  => :yellow
-        event :go,    :yellow => :green
+        event :slow, :green  => :yellow
+        event :go,   :yellow => :green
       }
 
       callbacks {
@@ -606,8 +606,8 @@ describe FiniteMachine, 'callbacks' do
       initial :green
 
       events {
-        event :slow,  :green  => :yellow
-        event :go,    :yellow => :green
+        event :slow, :green  => :yellow
+        event :go,   :yellow => :green
       }
 
       callbacks {
@@ -625,8 +625,8 @@ describe FiniteMachine, 'callbacks' do
       initial :green
 
       events {
-        event :slow,  :green  => :yellow
-        event :go,    :yellow => :green
+        event :slow, :green  => :yellow
+        event :go,   :yellow => :green
       }
 
       callbacks {
@@ -646,7 +646,7 @@ describe FiniteMachine, 'callbacks' do
   it "groups states from separate events with the same name" do
     callbacks = []
     fsm = FiniteMachine.define do
-      initial state: :initial, silent: false
+      initial :initial, silent: false
 
       events {
         event :bump, :initial => :low
@@ -720,7 +720,7 @@ describe FiniteMachine, 'callbacks' do
   it "groups states under event name" do
     callbacks = []
     fsm = FiniteMachine.define do
-      initial state: :initial, silent: false
+      initial :initial, silent: false
 
       events {
         event :bump, :initial => :low,
@@ -770,7 +770,7 @@ describe FiniteMachine, 'callbacks' do
   it "permits state and event with the same name" do
     called = []
     fsm = FiniteMachine.define do
-      initial state: :on_hook, silent: false
+      initial :on_hook, silent: false
 
       events {
         event :off_hook, :on_hook => :off_hook