golem_statemachine 0.9.5 → 1.1.0.pre2

data/README.rdoc

@@ -7,9 +7,8 @@ any Ruby object.
 
 The Finite State Machine pattern has many potential uses, but in practice you'll probably find it most useful in
 implementing complex business logic -- the kind that requires multi-page UML diagrams describing an entity's behavior
-over a series of events. Golem makes it much easier to implement and keep track of complicated, stateful behaviour,
-and the DSL you use to define your state machine in Ruby is specifically designed to make translation to and from UML
-easy.
+over a series of events. Golem's DSL is specifically designed to have close correspondence with UML diagrams. Golem
+also includes the ability to automatically generate UML sequence diagrams from statemachines using GraphViz.
 
 
 ==== Contents

data/golem_statemachine.gemspec

@@ -1,7 +1,7 @@
 
 $gemspec = Gem::Specification.new do |s|
   s.name     = 'golem_statemachine'
-  s.version  = '0.9.5'
+  s.version  = '1.1.0.pre2'
   s.authors  = ["Matt Zukowski"]
   s.email    = ["matt@roughest.net"]
   s.homepage = 'http://github.com/zuk/golem_statemachine'

data/lib/golem.rb

@@ -1,7 +1,6 @@
 require 'active_support/all'
-
 require 'golem/dsl/state_machine_def'
-require 'ruby-debug'
+
 module Golem
 
   def self.included(mod)
@@ -99,7 +98,7 @@ module Golem
         state ||= statemachine.initial_state
         state   = state.to_sym if state.is_a?(String)
 
-        raise InvalidStateError, "#{self} is in an unrecognized state (#{state.inspect})" unless statemachine.states[state]
+        raise InvalidStateError, "#{state} is in an unrecognized state (#{state.inspect})" unless statemachine.states[state]
 
         state   = statemachine.states[state].name
         

data/lib/golem/dsl/state_def.rb

@@ -22,6 +22,10 @@ module Golem
            @state.callbacks[:on_exit] = Golem::Model::Callback.new(options[:exit])
         end
         
+        if options[:comment]
+          @state.comment = options[:comment]
+        end
+        
         instance_eval(&block) if block
       end
 
@@ -40,6 +44,14 @@ module Golem
         raise Golem::DefinitionSyntaxError, "Provide either a callback method or a block, not both." if callback && block
         @state.callbacks[:on_exit] = Golem::Model::Callback.new(block || callback)
       end
+      
+      def comment(comment)
+        if @state.comment
+          @state.comment += "\n#{comment}"
+        else
+          @state.comment = comment
+        end
+      end
     end
   end
 end

data/lib/golem/dsl/transition_def.rb

@@ -14,12 +14,16 @@ module Golem
         else
           @to = @machine.get_or_define_state(options[:to])
         end
-
+        
         callbacks = {}
         callbacks[:on_transition] = options[:action] if options[:action]
 
         @transition = Golem::Model::Transition.new(@from, @to || @from, options[:guards], callbacks)
 
+        if options[:comment]
+          @transition.comment = options[:comment]
+        end
+
         instance_eval(&block) if block
 
         @from.transitions_on_event[@event] ||= []
@@ -46,6 +50,14 @@ module Golem
 
         @transition.callbacks[:on_transition] = Golem::Model::Callback.new(callback)
       end
+      
+      def comment(comment)
+        if @transition.comment
+          @transition.comment += "\n#{comment}"
+        else
+          @transition.comment = comment
+        end
+      end
     end
   end
 end

data/lib/golem/model/state.rb

@@ -6,6 +6,8 @@ module Golem
       attr_reader :name
       attr_reader :callbacks
       attr_reader :transitions_on_event
+      
+      attr_accessor :comment
 
       def initialize(name)
         name = name.to_sym unless name.is_a?(Symbol)

data/lib/golem/model/transition.rb

@@ -8,6 +8,8 @@ module Golem
       attr_reader :to
       attr_accessor :guards
       attr_accessor :callbacks
+      
+      attr_accessor :comment
 
       def initialize(from, to, guards = [], callbacks = {})
         @from = from

data/lib/golem/util/element_collection.rb

@@ -24,6 +24,10 @@ module Golem
       def each
         @collection.values.each{|v| yield v}
       end
+      
+      def empty?
+        @collection.empty?
+      end
 
       def values
         @collection.values

data/lib/golem/visualizer.rb

@@ -0,0 +1,190 @@
+begin
+  require 'graphviz' 
+rescue LoadError 
+  $stderr.puts "You must install the 'graphviz' gem to use this visualizer."
+  exit
+end
+
+begin
+  require 'htmlentities' 
+rescue LoadError 
+  $stderr.puts "You must install the 'htmlentities' gem to use this visualizer."
+  exit
+end
+
+module Golem
+  class Visualizer
+    def initialize(statemachine)    
+      @statemachine = statemachine
+    end
+    
+    def visualize(format, filename)
+      @state_nodes = {}
+      @current_path = []
+      
+      @graph = GraphViz.new(:G, 
+        :type => :digraph, 
+        :fontname => "Verdana", 
+        :concentrate => true)
+      
+      state = @statemachine.states[@statemachine.initial_state]
+      visualize_state(state)
+      
+      @graph.output(format => filename)
+    end
+    
+    protected
+    def visualize_state(state)
+      if @current_path.include?(state.name)
+        return
+      else
+        @current_path << state.name        
+        #puts @current_path.join(" / ")
+      end
+      
+      @current_path << state.name
+      
+      html = HTMLEntities.new
+      
+      if @state_nodes[state.name]
+        n = @state_nodes[state.name]
+      else
+        n = @graph.add_nodes(state.name.to_s)
+        
+        actions = []
+        if state.callbacks[:on_enter]
+          action_code = format_callback_code(state.callbacks[:on_enter])
+          unless action_code.nil? || action_code.strip.blank?
+            actions << "<br /><font face=''>enter/ </font><font face='Courier' point-size='11'>#{html.encode(action_code).gsub("\n","<br align='left' />    ")}</font>"
+          end
+        end
+        if state.callbacks[:on_exit]
+          action_code = format_callback_code(state.callbacks[:on_exit])
+          unless action_code.nil? || action_code.strip.blank?
+            actions << "<br /><font face=''>exit/ </font><font face='Courier' point-size='11'>#{html.encode(action_code).gsub("\n","<br align='left' />    ")}</font>"
+          end
+        end
+        
+        n[:fontname] = "Verdana"
+        n[:shape] = "box"
+        n[:style] = "rounded,filled"
+        
+        if @current_path.first == state.name
+          n[:fillcolor] = "palegreen"
+        elsif state.transitions_on_event.empty?
+          n[:fillcolor] = "red3"
+        else
+          n[:fillcolor] = "lightblue"
+        end
+        
+        comment = nil
+        if state.comment
+          comment = "<br /><font color=\"indigo\" font-face=\"Verdana-Italic\" point-size=\"11\">#{html.encode(state.comment).gsub(/\n/,'<br />')}</font>"
+        end
+        
+        n[:label] = "<<font>#{state.name}</font>#{comment}#{actions.join("<br align=\"left\" />")}>"
+        @state_nodes[state.name] = n
+      end
+      
+      tos = []
+      puts state.name.to_s
+      
+      @statemachine.events.each do |ev|
+        transitions = state.transitions_on_event[ev.name] || []
+        
+        if transitions.size > 1
+          dn = @graph.add_nodes("#{state.name}_#{ev.name}")
+          dn[:fontname] = "Verdana"
+          dn[:shape] = "diamond"
+          dn[:style] = "filled"
+          dn[:fillcolor] = "khaki1"
+          dn[:label] = ""
+          
+          de = @graph.add_edges(n, dn)
+          de[:label] = "<<font face=\"Verdana-Bold\">#{ev.name}</font>>"
+        else
+          dn = false
+          de = false
+        end
+        
+        transitions.each do |transition|
+          puts " --[ #{ev.name} ]--> #{transition.to.name}"
+          edge = @graph.add_edges(dn || n, transition.to.name.to_s)
+          
+          guard = nil
+          unless transition.guards.empty?
+            guard = transition.guards.collect do |g|
+              format_callback_code(g)
+            end.join(" and ")
+            
+            guard = "[#{guard.strip}]\n"
+          end
+          
+          action = nil
+          on_transition = transition.callbacks[:on_transition]
+          if on_transition
+            action = format_callback_code(on_transition)
+          end
+          
+          if action
+            action = "<br /> / <font face=\"Courier\" point-size=\"11\">#{html.encode(action).gsub(/\n/,'<br align="left" />')}</font> "
+          end
+          
+          if guard
+            guard = "<font face=\"Courier\" point-size=\"11\">#{html.encode(guard).gsub(/\n/,'<br />')}</font><br align=\"left\" />"
+          end
+          
+          comment = transition.comment
+          if comment
+            comment = "<font color=\"indigo\" font-face=\"Verdana-Italic\" point-size=\"11\">#{html.encode(comment).gsub(/\n/,'<br />')}</font>"
+          end
+          
+          if dn
+            edge[:label] = "<<font face=\"Verdana\">#{guard} #{action}#{comment}</font>>"
+          else
+            edge[:label] = "<<font face=\"Verdana\">#{guard}<font face=\"Verdana-Bold\"> #{html.encode(ev.name)} </font> #{action}#{comment}</font>>"
+          end
+          
+          tos << transition.to
+        end
+      end
+      
+      tos.each do |state|
+        visualize_state(state)
+      end
+    end
+    
+    def format_callback_code(cb)
+      raise ArgumentError, "Callback must be of type Golem::Model::Callback but is a #{callback.type}" unless
+        cb.kind_of?(Golem::Model::Callback)
+      
+      if cb.callback.kind_of?(Symbol)
+        action = cb.callback.to_s
+      else
+        callback_info = cb.to_s.match(/@(.*):([\d]+)/)
+        file = callback_info[1]
+        line = callback_info[2].to_i - 1
+        puts "#{file}:#{line}"
+        code = IO.readlines(file)[line].strip
+        if /\{(?:\|.+\|)?(.*)\}/ =~ code
+          callback_code = $~[1].strip
+        elsif /(do\s+\|.+\|)|(\{\s+\|)/ =~ code
+          matching = $~[0].include?("do") ? /end/ : /^\s*\}/ # FIXME: this is awful
+          line_code = ""
+          callback_code = ""
+          lines = IO.readlines(file)
+          first_indent = lines[line+1].match(/(^\s+)/)[1]
+          while true
+            line += 1 
+            line_code = lines[line]
+            break if line_code.match(matching) # FIXME, looking for end of block
+            next if line_code.match(/log/) # FIXME, trying to ignore log lines
+            callback_code << line_code.rstrip.gsub(/^#{first_indent}/,'') + "\n  "
+          end
+        end
+        
+        return callback_code
+      end
+    end
+  end
+end

data/test/problematic_test.rb

@@ -1,5 +1,4 @@
 require 'test_helper'
-require 'ruby-debug'
 
 # Tests specifically designed to address bugs/problems discovered along the way.
 class ProblematicTest < Test::Unit::TestCase
@@ -77,7 +76,7 @@ class ProblematicTest < Test::Unit::TestCase
           enter do |engine|
             engine.off = false
           end
-          on :start, :to => :running
+          on :put_in_gear, :to => :running
         end
       end
     end
@@ -91,5 +90,57 @@ class ProblematicTest < Test::Unit::TestCase
 
     assert_equal false, widget.off
   end
+  
+  def test_state_enter_and_exit_actions
+    @klass.instance_eval do
+      class_eval do
+        attr_accessor :off
+        attr_accessor :lights
+      end
+      
+      define_statemachine(:engine) do
+        initial_state :stopped
+        state :stopped do
+          enter do |engine|
+            engine.off = true
+            engine.lights = :off
+          end
+          exit do |engine|
+            engine.lights = :on
+          end
+          on :start, :to => :idle
+        end
+        state :idle do
+          enter do |engine|
+            engine.off = false
+          end
+          on :put_in_gear, :to => :running
+        end
+        state :running do
+          on :stop, :to => :stopped
+        end
+      end
+    end
+    
+    widget = @klass.new
+    
+    assert_equal :off, widget.lights
+    
+    widget.start!
+    
+    assert_equal :on, widget.lights
+    
+    widget.put_in_gear!
+    
+    assert_equal :on, widget.lights
+    
+    widget.stop!
+    
+    assert_equal :off, widget.lights
+    
+    widget.start!
+    
+    assert_equal :on, widget.lights
+  end
 end
 

metadata

@@ -1,12 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: golem_statemachine
 version: !ruby/object:Gem::Version 
-  prerelease: false
+  prerelease: true
   segments: 
+  - 1
+  - 1
   - 0
-  - 9
-  - 5
-  version: 0.9.5
+  - pre2
+  version: 1.1.0.pre2
 platform: ruby
 authors: 
 - Matt Zukowski
@@ -14,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-12-07 00:00:00 -05:00
+date: 2012-02-13 00:00:00 -05:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -70,6 +71,7 @@ files:
 - lib/golem/model/state_machine.rb
 - lib/golem/model/transition.rb
 - lib/golem/util/element_collection.rb
+- lib/golem/visualizer.rb
 - tasks/golem_statemachine_tasks.rake
 - test/active_record_test.rb
 - test/dsl_test.rb
@@ -105,11 +107,13 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: "0"
 required_rubygems_version: !ruby/object:Gem::Requirement 
   requirements: 
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version 
       segments: 
-      - 0
-      version: "0"
+      - 1
+      - 3
+      - 1
+      version: 1.3.1
 requirements: []
 
 rubyforge_project: