simplificator-fsm 0.2.4 → 0.3.0

data/README.markdown

@@ -9,18 +9,19 @@ FSM is a simple finite state machine
       define_fsm do
         # now define all the states
         # you can add :enter / :exit callbacks (callback can be a String, Symbol or Proc)
-        # these callbacks are triggered on any transition from/to this state
+        # these callbacks are triggered on any transition from/to this state.
         
         state(:gas)
         state(:liquid)
         state(:solid, :enter => :on_enter_solid, :exit => :on_exit_solid)
         
         # define all valid transitions (arguments are name of transition, from state name, to state name)
-        # you can define callbacks which are called only on this transition
-        transition(:heat_up, :solid, :liquid, :event => :liquified)
-        transition(:heat_up, :liquid, :gas)     # look mam.... two transitions with same name
-        transition(:cool_down, :gas, :liquid)
-        transition(:cool_down, :liquid, :solid)
+        # you can define callbacks which are called only on this transition as well as guards 
+        # guards prevent transition when they return nil/false
+        transition(:heat_up, :solid, :liquid, :event => :on_heat, :guard => :guard_something)
+        transition(:heat_up, :liquid, :gas, :event => :on_heat)     # look mam.... two transitions with same name
+        transition(:cool_down, :gas, :liquid, :event => :on_cool)
+        transition(:cool_down, :liquid, :solid, :event => :on_cool)
         
         # define the attribute which is used to store the state (defaults to :state)
         state(:state_of_material)
@@ -32,28 +33,59 @@ FSM is a simple finite state machine
       private
       # callbacks here...
       def ...
+      
+      # 
+      def guard_something()
+        
+      end
     end
     
     # then you can call these methods
     w = Water.new
-    w.heat  # the name of the transition is the name of the method
+    w.heat_up  # the name of the transition is the name of the method
     w.reachable_state_names
     w.available_transition_names
     w.cool_down # again... it's the name of the transition
     w.state_of_material
     
+    
+## Guards
+Guards are methods or Procs which can prevent a transition. To do so they just need to return false/nil. If no guard is specified
+then the transition is always executed.
+
+## Callbacks and arguments
+If the :enter/:exit callbacks are methods, then they are not passed any arguments, if it's a Proc, 
+then a single argument (the caller) is passed.
+Short: :enter/:exit methods must take 0 arguments, :enter/:exit Procs must take one argument.
+
+If :event and :guard callbacks are methods then they are passed all the arguments that were passed to the transition method.
+With Procs for :event and :guard the caller as well as all the arguments passed to the transition methods are passed.
+
+   
+## Order of callbacks/guards calls
+The callbacks/guards are called in following order if the guard returns __true__:
+  * :exit (state)
+  * :guard (transition)
+  * :event (transition)
+  * :enter (state) 
+  
+The callbacks/guards are called in following order if the guard returns __false__:
+  * :exit (state)
+  * :guard (transition)
+
+
 ## Graphviz / Dot format
 FSM supports the dot format of graphviz (http://www.graphviz.org/).
 If you have the graphviz tools installed (the dot executable must be on the path) then
 you can export a graph to png like this
-  # Export to water.png in the current dir
-  Water.dot    
-  # Export in another format. (see graphviz documentation for supported file formats)
-  Water.dot(:format => :foo)
-  # Change the extension (defaults to the format)
-  Water.dot(:format => :jpg, :extension => :jpeg)
-  # Specify a custom file
-  Water.dot(:outfile => '/afile.png')
+    # Export to water.png in the current dir
+    Water.graph    
+    # Export in another format. (see graphviz documentation for supported file formats)
+    Water.draw_graph(:format => :foo)
+    # Change the extension (defaults to the format)
+    Water.draw_graph(:format => :jpg, :extension => :jpeg)
+    # Specify a custom file
+    Water.draw_graph(:outfile => '/afile.png')
   
     
 ## Copyright

data/VERSION.yml

@@ -1,4 +1,4 @@
 --- 
 :major: 0
-:minor: 2
-:patch: 4
+:minor: 3
+:patch: 0

data/lib/fsm.rb

@@ -17,10 +17,10 @@ module FSM
       end
     end
     
-    def dot(options = {})
+    def draw_graph(options = {})
       machine = Machine[self]
       raise 'No FSM defined. Call define_fsm first' unless machine
-      machine.dot(options)
+      machine.draw_graph(options)
     end
     
   end

data/lib/fsm/machine.rb

@@ -19,7 +19,7 @@ module FSM
     
     def state(name, options = {})
       raise "State is already defined: '#{name}'" if self.state_for_name(name, true)
-      self.states << State.new(name, options)
+      self.states << State.new(name, @target_class, options)
       self.initial_state_name=(name) unless self.initial_state_name
     end
     
@@ -79,14 +79,19 @@ module FSM
       state
     end
     
-    def to_dot
-      dots = self.transitions.map do |transition|
-        "  #{transition.from.name} -> #{transition.to.name}"
+    # Convert this state machine to the dot format of graphviz
+    def to_dot(options = {})
+      s = self.states.map do |state|
+        "  #{state.to_dot(options)};"
       end
-      "digraph FSM {\n#{dots.join(";\n")}\n}"
+      t = self.transitions.map do |transition|
+        "  #{transition.to_dot(options)};"
+      end
+      "digraph FSM_#{@target_class.name} {\n#{s.join("\n")}\n\n#{t.join("\n")}\n}"
     end
     
-    def dot(options = {})
+    # 
+    def draw_graph(options = {})
       format = options[:format] || :png
       extension = options[:extension] || format
       file_name = options[:outfile] || "#{@target_class.name.downcase}.#{extension}" 
@@ -115,10 +120,14 @@ module FSM
           to_state = transition.to
           
           from_state.exit(self)
-          transition.fire_event(self, args)
-          to_state.enter(self)
-          Machine.set_current_state_name(self, to_state.name)
-          true # at the moment always return true ... as soon as we have guards or thelike this could be false as well 
+          if transition.fire?(self, args)
+            transition.fire_event(self, args)
+            to_state.enter(self)
+            Machine.set_current_state_name(self, to_state.name)
+            true
+          else
+            false
+          end
         end
       end
     end

data/lib/fsm/state.rb

@@ -10,10 +10,11 @@ module FSM
     # options
     #  * :enter : a symbol or string or Proc
     #  * :exit : a symbol or string or Proc
-    def initialize(name, options = {})
-      raise ArgumentError.new('Name is required') unless name
+    def initialize(name, target_class, options = {})
+      raise ArgumentError.new('name and target_class is required') unless name && target_class
       assert_options(options, [:enter, :exit])
       @name = name
+      @target_class = target_class
       @enter = Executable.new options[:enter] if options.has_key?(:enter)
       @exit = Executable.new options[:exit] if options.has_key?(:exit)
       @transitions = {}
@@ -40,10 +41,28 @@ module FSM
     def to_states
       @transitions.map { |to_name, transition| transition.to}
     end
+    def final?
+      @transitions.empty?
+    end
+    
+    def initial?
+      Machine[@target_class].initial_state_name == self.name
+    end
     
     def to_s
-      "State '#{self.name}'"
+      "State '#{self.name}' is "
+    end
+    
+    def to_dot(options = {})
+      
+      if final?
+        attrs = "style=bold"
+      elsif initial?
+        attrs = "style=bold, label=\"#{self.name}\\n(initial)\""
+      else
+        attrs = ""
+      end
+      "#{self.name}[#{attrs}]"
     end
-
   end
 end

data/lib/fsm/transition.rb

@@ -1,22 +1,31 @@
 module FSM
   class Transition
     include FSM::Options::InstanceMethods
-    attr_accessor(:name, :from, :to, :event)
+    attr_accessor(:name, :from, :to, :event, :guard)
     def initialize(name, from, to, options = {})
       raise ArgumentError.new("name, from and to are required but were '#{name}', '#{from}' and '#{to}'") unless name && from && to
-      assert_options(options, [:event])
+      assert_options(options, [:event, :guard])
       self.name = name
       self.from = from
       self.to = to
       self.event = Executable.new options[:event] if options.has_key?(:event)
+      self.guard = Executable.new options[:guard] if options.has_key?(:guard)
     end
     
     def fire_event(target, args)
       self.event.execute(target, *args) if self.event
-    end    
+    end  
+    
+    def fire?(target, args)
+      self.guard ? self.guard.execute(target, *args) : true
+    end  
     
     def to_s
       "Transition from #{self.from.name} -> #{self.to.name} with event #{self.event}"
-    end    
+    end  
+    
+    def to_dot(options = {})
+      "#{self.from.name} -> #{self.to.name} [label=\"#{self.name}\"]"
+    end  
   end
 end

data/test/state_test.rb

@@ -7,15 +7,15 @@ class StateTest < Test::Unit::TestCase
         FSM::State.new(nil, nil, nil)
       end
      
-      FSM::State.new('bla')
+      FSM::State.new('bla', self)
     end
     
     should 'allow only valid options' do
       assert_raise(ArgumentError) do
-        FSM::State.new('bla', :foo => 12)
+        FSM::State.new('bla', self, :foo => 12)
       end
-      FSM::State.new('bla', :enter => :some)
-      FSM::State.new('bla', :exit => :some)
+      FSM::State.new('bla', self, :enter => :some)
+      FSM::State.new('bla', self, :exit => :some)
     end
   end
 end

data/test/transition_test.rb

@@ -5,8 +5,8 @@ class TransitionTest < Test::Unit::TestCase
     
     
     should 'require name, from and to' do
-      bli_state = FSM::State.new('bli')
-      blo_state = FSM::State.new('blo')
+      bli_state = FSM::State.new('bli', self)
+      blo_state = FSM::State.new('blo', self)
       assert_raise(ArgumentError) do
         FSM::Transition.new(nil, nil, nil)
       end
@@ -33,12 +33,13 @@ class TransitionTest < Test::Unit::TestCase
     end
     
     should 'allow only valid options' do
-      bli_state = FSM::State.new('bli')
-      blo_state = FSM::State.new('blo')
+      bli_state = FSM::State.new('bli', self)
+      blo_state = FSM::State.new('blo', self)
       assert_raise(ArgumentError) do
         FSM::Transition.new(:name, bli_state, blo_state, :foo => 12)
       end
       FSM::Transition.new(:name, bli_state, blo_state, :event => :some)
+      FSM::Transition.new(:name, bli_state, blo_state, :guard => :some)
     end
   end
 end

data/test/water_sample_test.rb

@@ -2,6 +2,7 @@ require 'test_helper'
 
 class Water
   attr_accessor(:state_of_material)
+  attr_accessor(:temperature)
   include FSM
   define_fsm do
     # now define all the states
@@ -14,10 +15,10 @@ class Water
     # define all valid transitions (name, from, to). This will define a method with the given name.
     # you can define :event callback which is called only on this transition and receives the arguments passed to the
     # transition method
-    transition(:heat_up, :solid, :liquid)
-    transition(:heat_up, :liquid, :gas)
-    transition(:cool_down, :gas, :liquid)
-    transition(:cool_down, :liquid, :solid)
+    transition(:heat_up, :solid, :liquid, :event => :on_heat_up, :guard => :guard_solid_to_liquid)
+    transition(:heat_up, :liquid, :gas, :event => :on_heat_up, :guard => :guard_liquid_to_gas)
+    transition(:cool_down, :gas, :liquid, :event => :on_cool_down, :guard => :guard_gas_to_liquid)
+    transition(:cool_down, :liquid, :solid, :event => :on_cool_down, :guard => :guard_liquid_to_solid)
     
     # define the attribute which is used to store the state (defaults to :state)
     state_attribute(:state_of_material)
@@ -25,12 +26,42 @@ class Water
     # define the initial state (defaults to the first state defined - :gas in this sample)
     initial(:solid)
   end
+  
+  def initialize(temperature = -20)
+    self.temperature = temperature
+  end
+  
   private
   def on_enter_solid()
   end
   def on_exit_solid()
   end
+  
+  def guard_solid_to_liquid(delta)
+    self.temperature + delta >= 0
+  end
+  def guard_liquid_to_gas(delta)
+    self.temperature + delta >= 100
+  end
+  
+  def guard_gas_to_liquid(delta)
+    self.temperature - delta < 100
+  end
+  
+  def guard_liquid_to_solid(delta)
+    self.temperature - delta < 0
+  end
+  
+  def on_heat_up(delta)
+    self.temperature += delta
+  end
+  
+  def on_cool_down(delta)
+    self.temperature -= delta
+  end
 end
+# Draw the the state graph
+#Water.draw_graph(:format => :svg)
 
 class WaterSampleTest < Test::Unit::TestCase
   context 'Water' do
@@ -38,13 +69,14 @@ class WaterSampleTest < Test::Unit::TestCase
     should 'cycle through material states' do
       w = Water.new
       assert_equal(:solid, w.state_of_material)
-      w.heat_up
+      assert w.heat_up(30)
       assert_equal(:liquid, w.state_of_material)
-      w.heat_up
+      assert !w.heat_up(10)
+      assert w.heat_up(90)
       assert_equal(:gas, w.state_of_material)
-      w.cool_down
+      assert w.cool_down(50)
       assert_equal(:liquid, w.state_of_material)
-      w.cool_down
+      assert w.cool_down(70)
       assert_equal(:solid, w.state_of_material)
       
       assert_raise(FSM::InvalidStateTransition) do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: simplificator-fsm
 version: !ruby/object:Gem::Version 
-  version: 0.2.4
+  version: 0.3.0
 platform: ruby
 authors: 
 - simplificator