finite_machine 0.7.1 → 0.8.0

data/lib/finite_machine/dsl.rb

@@ -67,9 +67,9 @@ module FiniteMachine
     #
     # @api public
     def initial(value)
-      state, name, self.defer = parse(value)
-      self.initial_event      = name
-      machine.event(name, from: FiniteMachine::DEFAULT_STATE, to: state)
+      state, name, self.defer, silent = parse(value)
+      self.initial_event = name
+      machine.event(name, FiniteMachine::DEFAULT_STATE => state, silent: silent)
     end
 
     # Trigger initial event
@@ -158,12 +158,13 @@ module FiniteMachine
     #
     # @api private
     def parse(value)
-      unless value.is_a?(Hash)
-        [value, FiniteMachine::DEFAULT_EVENT_NAME, false]
-      else
+      if value.is_a?(Hash)
         [value.fetch(:state) { raise_missing_state },
          value.fetch(:event) { FiniteMachine::DEFAULT_EVENT_NAME },
-         value.fetch(:defer) { false }]
+         value.fetch(:defer) { false },
+         value.fetch(:silent) { true }]
+      else
+        [value, FiniteMachine::DEFAULT_EVENT_NAME, false, true]
       end
     end
 
@@ -176,8 +177,8 @@ module FiniteMachine
     end
   end # DSL
 
+  # A DSL for describing events
   class EventsDSL < GenericDSL
-
     # Create event and associate transition
     #
     # @example
@@ -191,13 +192,19 @@ module FiniteMachine
       sync_exclusive do
         attributes = attrs.merge!(name: name)
         FiniteMachine::StateParser.new(attrs).parse_states do |from, to|
-          attributes.merge!(parsed_states: { from => to })
-          Transition.create(machine, attributes)
+          if block_given?
+            merger = ChoiceMerger.new(self, attributes)
+            merger.instance_eval(&block)
+          else
+            attributes.merge!(parsed_states: { from => to })
+            Transition.create(machine, attributes)
+          end
         end
       end
     end
   end # EventsDSL
 
+  # A DSL for describing error conditions
   class ErrorsDSL < GenericDSL
     # Add error handler
     #

data/lib/finite_machine/event.rb

@@ -14,10 +14,16 @@ module FiniteMachine
     # The reference to the state machine for this event
     attr_threadsafe :machine
 
+    # The silent option for this transition
+    attr_threadsafe :silent
+
+    # Initialize an Event
+    #
     # @api private
     def initialize(machine, attrs = {})
       @machine = machine
       @name    = attrs.fetch(:name, DEFAULT_STATE)
+      @silent  = attrs.fetch(:silent, false)
       @state_transitions = []
       # TODO: add event conditions
     end
@@ -45,21 +51,46 @@ module FiniteMachine
     #
     # @api private
     def next_transition
-      state_transitions.find do |transition|
-        transition.from_state == machine.current ||
-          transition.from_state == ANY_STATE
-      end || state_transitions.first
+      sync_shared do
+        state_transitions.find do |transition|
+          transition.from_state == machine.current ||
+            transition.from_state == ANY_STATE
+        end || state_transitions.first
+      end
+    end
+
+    # Find transition matching conditions
+    #
+    # @param [Array[Object]] args
+    #
+    # return FiniteMachine::TransitionChoice
+    #
+    # @api private
+    def find_transition(*args)
+      sync_shared do
+        state_transitions.find { |trans| trans.check_conditions(*args) }
+      end
     end
 
     # Trigger this event
     #
+    # If silent option is passed the event will not fire any callbacks
+    #
+    # @example
+    #   transition = Transition.create(machine, {})
+    #   transition.call
+    #
     # @return [nil]
     #
     # @api public
     def call(*args, &block)
       sync_exclusive do
         _transition = next_transition
-        machine.send(:transition, _transition, *args, &block)
+        if silent
+          _transition.call(*args, &block)
+        else
+          machine.send(:transition, _transition, *args, &block)
+        end
       end
     end
 

data/lib/finite_machine/observer.rb

@@ -142,8 +142,8 @@ module FiniteMachine
     #
     # @api private
     def handle_callback(hook, event)
-      trans_event = TransitionEvent.build(event.transition)
       data        = event.data
+      trans_event = TransitionEvent.build(event.transition, *data)
       callable    = create_callable(hook)
 
       if hook.is_a?(Async)

data/lib/finite_machine/state_machine.rb

@@ -165,13 +165,19 @@ module FiniteMachine
     # @example
     #   fsm.can?(:go) # => true
     #
+    # @example
+    #   fsm.can?(:go, 'Piotr')  # checks condition with parameter 'Piotr'
+    #
     # @param [String] event
     #
     # @return [Boolean]
     #
     # @api public
-    def can?(event)
-      transitions[event].key?(current) || transitions[event].key?(ANY_STATE)
+    def can?(*args, &block)
+      event       = args.shift
+      valid_state = transitions[event].key?(current)
+      valid_state ||= transitions[event].key?(ANY_STATE)
+      valid_state &&= events_chain[event].next_transition.valid?(*args, &block)
     end
 
     # Checks if event cannot be triggered
@@ -184,8 +190,8 @@ module FiniteMachine
     # @return [Boolean]
     #
     # @api public
-    def cannot?(event)
-      !can?(event)
+    def cannot?(*args, &block)
+      !can?(*args, &block)
     end
 
     # Checks if terminal state has been reached
@@ -197,6 +203,17 @@ module FiniteMachine
       is?(final_state)
     end
 
+    # Restore this machine to a known state
+    #
+    # @param [Symbol] state
+    #
+    # @return nil
+    #
+    # @api public
+    def restore!(state)
+      sync_exclusive { self.state = state }
+    end
+
     # String representation of this machine
     #
     # @return [String]
@@ -243,7 +260,7 @@ module FiniteMachine
         notify HookEvent::Exit, _transition, *args
 
         begin
-          _transition.call
+          _transition.call(*args)
 
           notify HookEvent::Transition, _transition, *args
         rescue Exception => e

data/lib/finite_machine/state_parser.rb

@@ -7,6 +7,8 @@ module FiniteMachine
 
     attr_threadsafe :attrs
 
+    BLACKLIST = [:name, :if, :unless, :silent].freeze
+
     # Initialize a StateParser
     #
     # @example
@@ -83,7 +85,7 @@ module FiniteMachine
     # @api private
     def ensure_only_states!(attrs)
       _attrs = attrs.dup
-      [:name, :if, :unless].each { |key| _attrs.delete(key) }
+      BLACKLIST.each { |key| _attrs.delete(key) }
       raise_not_enough_transitions unless _attrs.any?
       _attrs
     end

data/lib/finite_machine/transition.rb

@@ -29,6 +29,9 @@ module FiniteMachine
     # All states for this transition event
     attr_threadsafe :map
 
+    # Silence callbacks
+    attr_threadsafe :silent
+
     # Initialize a Transition
     #
     # @param [StateMachine] machine
@@ -39,6 +42,7 @@ module FiniteMachine
       @machine     = machine
       @name        = attrs.fetch(:name, DEFAULT_STATE)
       @map         = attrs.fetch(:parsed_states, {})
+      @silent      = attrs.fetch(:silent, false)
       @from_states = @map.keys
       @to_states   = @map.values
       @from_state  = @from_states.first
@@ -60,7 +64,7 @@ module FiniteMachine
     #
     # @api public
     def self.create(machine, attrs = {})
-      _transition = self.new(machine, attrs)
+      _transition = new(machine, attrs)
       _transition.update_transitions
       _transition.define_state_methods
       _transition.define_event
@@ -72,8 +76,13 @@ module FiniteMachine
     # @return [Symbol]
     #
     # @api public
-    def to_state
-      machine.transitions[name][from_state]
+    def to_state(*args)
+      if machine.transitions[name][from_state].is_a? Array
+        found_trans = machine.events_chain[name].find_transition(*args)
+        found_trans.map[from_state]
+      else
+        machine.transitions[name][from_state]
+      end
     end
 
     # Reduce conditions
@@ -84,6 +93,17 @@ module FiniteMachine
         @unless.map { |c| Callable.new(c).invert }
     end
 
+    # Verify conditions returning true if all match, false otherwise
+    #
+    # @return [Boolean]
+    #
+    # @api private
+    def check_conditions(*args, &block)
+      conditions.all? do |condition|
+        condition.call(machine.target, *args, &block)
+      end
+    end
+
     # Check if moved to different state or not
     #
     # @param [Symbol] state
@@ -106,19 +126,27 @@ module FiniteMachine
     #
     # @api public
     def valid?(*args, &block)
-      conditions.all? do |condition|
-        condition.call(machine.target, *args, &block)
+      if machine.transitions[name][from_state].is_a? Array
+        machine.events_chain[name].state_transitions.any? do |trans|
+          trans.check_conditions(*args, &block)
+        end
+      else
+        check_conditions(*args, &block)
       end
     end
 
     # Add transition to the machine
     #
-    # @return [Transition]
+    # @return [FiniteMachine::Transition]
     #
     # @api private
     def update_transitions
       from_states.each do |from|
-        machine.transitions[name][from] = map[from] || ANY_STATE
+        if value = machine.transitions[name][from]
+          machine.transitions[name][from] = [value, map[from]].flatten
+        else
+          machine.transitions[name][from] = map[from] || ANY_STATE
+        end
       end
     end
 
@@ -158,7 +186,7 @@ module FiniteMachine
     #
     # @api private
     def define_event_transition(name)
-      _event = FiniteMachine::Event.new(machine, name: name)
+      _event = FiniteMachine::Event.new(machine, name: name, silent: silent)
       _event << self
       machine.events_chain[name] = _event
 
@@ -182,12 +210,17 @@ module FiniteMachine
     # @return [nil]
     #
     # @api private
-    def call
+    def call(*args)
       sync_exclusive do
         return if cancelled
         transitions     = machine.transitions[name]
         self.from_state = machine.state
-        machine.state   = transitions[machine.state] || transitions[ANY_STATE] || name
+        if machine.transitions[name][from_state].is_a? Array
+          found_trans   = machine.events_chain[name].find_transition(*args)
+          machine.state = found_trans.to_states.first
+        else
+          machine.state   = transitions[machine.state] || transitions[ANY_STATE] || name
+        end
         machine.initial_state = machine.state if from_state == DEFAULT_STATE
       end
     end

data/lib/finite_machine/transition_event.rb

@@ -17,11 +17,11 @@ module FiniteMachine
     # @return [self]
     #
     # @api private
-    def self.build(transition)
+    def self.build(transition, *data)
       instance = new
       instance.name = transition.name
       instance.from = transition.from_state
-      instance.to   = transition.to_state
+      instance.to   = transition.to_state(*data)
       instance
     end
   end # TransitionEvent

data/lib/finite_machine/version.rb

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

data/spec/spec_helper.rb

@@ -30,7 +30,7 @@ RSpec.configure do |config|
 
   # Remove defined constants
   config.before :each do
-    [:Car, :Logger].each do |class_name|
+    [:Car, :Logger, :Bug, :User].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 :green
+      initial state: :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
+      initial state: :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 :green
+      initial state: :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 :previous
+      initial state: :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 :green
+      initial state: :green, silent: false
 
       events {
         event :slow,  :green  => :yellow
@@ -549,7 +549,7 @@ describe FiniteMachine, 'callbacks' do
   it "triggers callbacks only once" do
     called = []
     fsm = FiniteMachine.define do
-      initial :green
+      initial state: :green, silent: false
 
       events {
         event :slow,  :green  => :yellow
@@ -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 :initial
+      initial state: :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 :initial
+      initial state: :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 :on_hook
+      initial state: :on_hook, silent: false
 
       events {
         event :off_hook, :on_hook => :off_hook
@@ -795,4 +795,25 @@ describe FiniteMachine, 'callbacks' do
       'on_enter_on_hook'
     ]);
   end
+
+  it "allows to selectively silence events" do
+    called = []
+    fsm = FiniteMachine.define do
+      initial :yellow
+
+      events {
+        event :go,   :yellow => :green, silent: true
+        event :stop, :green  => :red
+      }
+
+      callbacks {
+        on_enter :green do |event| called << 'on_enter_yellow' end
+        on_enter :red   do |event| called << 'on_enter_red' end
+      }
+    end
+    expect(fsm.current).to eq(:yellow)
+    fsm.go
+    fsm.stop
+    expect(called).to eq(['on_enter_red'])
+  end
 end