state_machines-graphviz 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: b375be8fce2b404843e60ffc947edb7d7b37a5e4
-  data.tar.gz: e46a7734205fd1ff0946dacb72195e82e1863d5a
+SHA256:
+  metadata.gz: 90020c1871d32a31894619ff9883ae27e08210499cd4a1c0361b18ad503c04b1
+  data.tar.gz: 9f206b3af3589f1072c8514b182d57c066e1de9179effafb6351a63471f8d61f
 SHA512:
-  metadata.gz: db7731a6a0236d51ca0a888870ab4f0bf1670ade1832051b2e84bd7220290b8ac5b86d473c089608aeb667388c70665fb9f2acf10cc89d59ee57d7f76fe59965
-  data.tar.gz: 854bb07b3eff8a50165b6bbc7012e2304259711d768238d5a0fbf88f02898f6e5a9730f36971a5c5d6f810cc87d30a649e9bfbf33a62230e1ff1ef99c7eda6c8
+  metadata.gz: cabca272749f9e4e5928cea279b45503e78268b5060e6acb6b50e61fcd5ef31800537ad5da64e7730afceeffaf3f560f18d8e0e96104ab8e00cab15acc27371f
+  data.tar.gz: d410ac462911bd82ae5827c71045cef33b4e1413d0abb079f1e1124c1f58fe337b2c4313d2281aabc39bf9a51e92cb7666c191972c365badd83f4feea9749b90

data/LICENSE.txt

@@ -1,5 +1,5 @@
 Copyright (c) 2006-2012 Aaron Pfeifer
-Copyright (c) 2014 Abdelkader Boudih
+Copyright (c) 2014-2023 Abdelkader Boudih
 
 MIT License
 

data/README.md

@@ -1,12 +1,13 @@
 # StateMachines::Graphviz
 
-TODO: Write a gem description
+This adds support for generating di-graphs based on the
+events, states, and transitions defined for a state machine using [GraphViz](http://www.graphviz.org).
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
-    gem 'state_machine2-graphviz' , group: :development
+    gem 'state_machines-graphviz' , group: :development
 
 And then execute:
 
@@ -14,15 +15,80 @@ And then execute:
 
 Or install it yourself as:
 
-    $ gem install state_machine2-graphviz
+    $ gem install state_machines-graphviz
 
 ## Usage
 
-TODO: Write usage instructions here
+The default output folder for the images is `doc/state_machines`.
+
+#### Examples
+
+To generate a graph for a specific file / class:
+
+```bash
+rake state_machines:draw FILE=vehicle.rb CLASS=Vehicle
+```
+From a Rails app directory:
+
+```bash
+rake state_machines:draw CLASS=Vehicle
+```
+
+To save files to a specific path:
+
+```bash
+rake state_machines:draw FILE=vehicle.rb CLASS=Vehicle TARGET=files
+```
+
+To customize the image format / orientation:
+
+```bash
+rake state_machines:draw FILE=vehicle.rb CLASS=Vehicle FORMAT=jpg ORIENTATION=landscape
+```
+
+See http://rdoc.info/github/glejeune/Ruby-Graphviz/GraphViz/Constants for the list of
+supported image formats.  If resolution is an issue, the svg format may offer
+better results.
+
+To generate multiple state machine graphs:
+
+```bash
+rake state_machines:draw FILE=vehicle.rb,car.rb CLASS=Vehicle,Car
+```
+
+To use human state / event names:
+
+```bash
+rake state_machines:draw FILE=vehicle.rb CLASS=Vehicle HUMAN_NAMES=true
+```
+
+**Note** that this will generate a different file for every state machine defined
+in the class.  The generated files will use an output filename of the format
+`#{class_name}_#{machine_name}.#{format}`.
+
+For examples of actual images generated using this task, see those under the
+examples folder.
+
+#### Example output
+
+Generate the sample diagram used in this README:
+
+```bash
+bundle exec ruby script/generate_example.rb
+```
+
+![Switch state machine](doc/switch.svg)
+
+### Interactive graphs
+
+Jean Bovet's [Visual Automata Simulator](https://github.com/NimaGhaedsharafi/VAS)
+is a great tool for "simulating, visualizing and transforming finite state
+automata and Turing Machines".  It can help in the creation of states and events
+for your models.  It is cross-platform, written in Java.
 
 ## Contributing
 
-1. Fork it ( https://github.com/seuros/state_machine2-graphviz/fork )
+1. Fork it ( https://github.com/state-machines/state_machines-graphviz/fork )
 2. Create your feature branch (`git checkout -b my-new-feature`)
 3. Commit your changes (`git commit -am 'Add some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)

data/lib/state_machines/graphviz/graph.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module StateMachines
   # Provides a set of higher-order features on top of the raw GraphViz graphs
   class Graph < GraphViz
@@ -23,12 +25,10 @@ module StateMachines
     #   "landscape").  Default is "portrait".
     def initialize(name, options = {})
       options = { path: 'doc/state_machines', format: 'png', font: 'Arial', orientation: 'portrait' }.merge(options)
-      options.assert_valid_keys(:path, :format, :font, :orientation)
+      StateMachines::OptionsValidator.assert_valid_keys!(options, :path, :format, :font, :orientation)
 
-      # TODO fail if path cannot be created or readonly
-      unless Dir.exist? options[:path]
-        FileUtils.mkpath(options[:path])
-      end
+      # TODO: fail if path cannot be created or readonly
+      FileUtils.mkpath(options[:path]) unless Dir.exist? options[:path]
       @font = options[:font]
       @file_path = File.join(options[:path], "#{name}.#{options[:format]}")
       @file_format = options[:format]

data/lib/state_machines/graphviz/renderer.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require 'state_machines-diagram'
+
+module StateMachines
+  module Graphviz
+    module Renderer
+      extend self
+
+      def draw_machine(machine, io: $stdout, **options)
+        diagram, builder = StateMachines::Diagram::Renderer.build_state_diagram(machine, options)
+        graph_options = options.dup
+        name = graph_options.delete(:name) || "#{machine.owner_class.name}_#{machine.name}"
+
+        draw_options = { human_name: false }
+        draw_options[:human_name] = graph_options.delete(:human_names) if graph_options.include?(:human_names)
+
+        graph = Graph.new(name, graph_options)
+        render_diagram(graph, diagram, builder, draw_options)
+        graph.output
+        graph
+      end
+
+      def draw_state(state, graph, options = {}, io = $stdout)
+        node = graph.add_nodes(
+          state.name ? state.name.to_s : 'nil',
+          label: state.description(options),
+          width: '1',
+          height: '1',
+          shape: state.final? ? 'doublecircle' : 'ellipse'
+        )
+
+        graph.add_edges(graph.add_nodes('starting_state', shape: 'point'), node) if state.initial?
+        true
+      end
+
+      def draw_event(event, graph, options = {}, io = $stdout)
+        machine = event.machine
+        valid_states = machine.states.by_priority.map(&:name)
+        event_label = options[:human_name] ? event.human_name(machine.owner_class) : event.name.to_s
+
+        event.branches.each do |branch|
+          draw_branch_with_label(branch, graph, event_label, machine, valid_states)
+        end
+
+        true
+      end
+
+      def draw_branch(branch, graph, event, valid_states, io = $stdout)
+        machine = event.machine
+        draw_branch_with_label(branch, graph, event.name.to_s, machine, valid_states)
+        true
+      end
+
+      private
+
+      def render_diagram(graph, diagram, builder, draw_options)
+        state_lookup = build_state_lookup(builder.machine)
+        state_metadata = builder&.state_metadata || {}
+        start_node = nil
+
+        diagram.states.each do |state_node|
+          metadata = state_metadata[state_node.id] || {}
+          state = state_lookup[state_node.id]
+          label = state ? state.description(human_name: draw_options[:human_name]) : (state_node.label || state_node.id)
+          shape = metadata[:type] == 'final' ? 'doublecircle' : 'ellipse'
+
+          node = graph.add_nodes(
+            graph_node_id(state_node.id),
+            label: label,
+            width: '1',
+            height: '1',
+            shape: shape
+          )
+
+          if metadata[:type] == 'initial'
+            start_node ||= graph.add_nodes('starting_state', shape: 'point')
+            graph.add_edges(start_node, node)
+          end
+        end
+
+        transition_metadata = transition_metadata_map(builder)
+        diagram.transitions.each do |transition|
+          metadata = transition_metadata[transition] || {}
+          callbacks = metadata[:callbacks] || {}
+
+          graph.add_edges(
+            graph_node_id(transition.source_state_id),
+            graph_node_id(transition.target_state_id),
+            label: transition.label.to_s,
+            labelfontsize: 10,
+            taillabel: Array(callbacks[:before]).compact.join("\n"),
+            headlabel: Array(callbacks[:after]).compact.join("\n")
+          )
+        end
+      end
+
+      def build_state_lookup(machine)
+        machine.states.each_with_object({}) do |state, memo|
+          key = state.name ? state.name.to_s : 'nil_state'
+          memo[key] = state
+        end
+      end
+
+      def graph_node_id(diagram_state_id)
+        diagram_state_id == 'nil_state' ? 'nil' : diagram_state_id
+      end
+
+      def transition_metadata_map(builder)
+        Array(builder&.transition_metadata).each_with_object({}) do |metadata, memo|
+          transition = metadata[:transition]
+          memo[transition] = metadata if transition
+        end
+      end
+
+      def draw_branch_with_label(branch, graph, event_label, machine, valid_states)
+        branch.state_requirements.each do |state_requirement|
+          from_states = state_requirement[:from].filter(valid_states)
+
+          if state_requirement[:to].values.empty?
+            loopback = true
+          else
+            to_state = state_requirement[:to].values.first
+            to_state = to_state ? to_state.to_s : 'nil'
+            loopback = false
+          end
+
+          from_states.each do |from_state|
+            from_state = from_state ? from_state.to_s : 'nil'
+            graph.add_edges(
+              from_state,
+              loopback ? from_state : to_state,
+              label: event_label,
+              labelfontsize: 10,
+              taillabel: callback_method_names(machine, branch, :before).join("\n"),
+              headlabel: callback_method_names(machine, branch, :after).join("\n")
+            )
+          end
+        end
+      end
+
+      def callback_method_names(machine, branch, type)
+        event_name = branch.event_requirement.values.first
+        machine.callbacks[type].select do |callback|
+          callback.branch.matches?(branch,
+                                   from: branch.state_requirements.map { |req| req[:from] },
+                                   to: branch.state_requirements.map { |req| req[:to] },
+                                   on: event_name)
+        end.flat_map do |callback|
+          callback.instance_variable_get('@methods')
+        end.compact
+      end
+    end
+  end
+end

data/lib/state_machines/graphviz/version.rb

@@ -1,6 +1,8 @@
+# frozen_string_literal: true
+
 module StateMachines
   # Gem version
   module Graphviz
-    VERSION = '0.0.1'
+    VERSION = '0.1.0'
   end
 end

data/lib/state_machines/graphviz.rb

@@ -1,5 +1,39 @@
+# frozen_string_literal: true
+
 require 'state_machines'
 require 'graphviz'
-require 'state_machines/graphviz/monkeypatch'
 require 'state_machines/graphviz/graph'
+require 'state_machines/graphviz/renderer'
 require 'state_machines/graphviz/version'
+
+module StateMachines
+  module Graphviz
+    module_function
+
+    def draw(class_names, options = {})
+      if class_names.nil? || class_names.to_s.split(',').empty?
+        raise ArgumentError, 'At least one class must be specified'
+      end
+
+      # Load any files
+      if (files = options.delete(:file))
+        files.split(',').each { |file| require file }
+      end
+
+      class_names.to_s.split(',').each do |class_name|
+        # Navigate through the namespace structure to get to the class
+        klass = Object
+        class_name.split('::').each do |name|
+          klass = klass.const_defined?(name) ? klass.const_get(name) : klass.const_missing(name)
+        end
+
+        # Draw each of the class's state machines
+        klass.state_machines.each_value do |machine|
+          machine.draw(**options)
+        end
+      end
+    end
+  end
+end
+
+require 'state_machines/tasks/railtie' if defined?(Rails)

data/lib/state_machines/tasks/railtie.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require 'state_machines/graphviz'
+require 'rails'
+module StateMachines
+  class Railtie < Rails::Railtie
+    rake_tasks do
+      load 'state_machines/tasks/state_machines.rake'
+    end
+  end
+end

data/lib/state_machines/tasks/state_machines.rake

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require 'state_machines/graphviz'
+
+require File.join("#{File.dirname(__FILE__)}/state_machines")

data/lib/state_machines-graphviz.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'state_machines-diagram'
+require 'state_machines/graphviz'
+require 'state_machines/graphviz/renderer'
+
+# Set the renderer to use graphviz
+StateMachines::Machine.renderer = StateMachines::Graphviz::Renderer

data/{spec → test}/files/switch.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 class Switch
   def self.name
     @name ||= "Switch_#{rand(1_000_000)}"

data/test/graph_default_test.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require './test/test_helper'
+describe StateMachines::Graph do
+  def setup
+    @graph = StateMachines::Graph.new('test')
+  end
+
+  def test_should_have_a_default_font
+    assert_equal('Arial', @graph.font)
+  end
+
+  def test_should_use_current_directory_for_filepath
+    assert_equal('doc/state_machines/test.png', @graph.file_path)
+  end
+
+  def test_should_have_a_default_file_format
+    assert_equal('png', @graph.file_format)
+  end
+
+  def test_should_have_a_default_orientation
+    assert_equal('TB', @graph[:rankdir].source)
+  end
+end

data/test/graph_edges_test.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative 'test_helper'
+describe StateMachines::Graph do
+  def setup
+    @graph = StateMachines::Graph.new('test')
+    @graph.add_nodes('parked', shape: 'ellipse')
+    @graph.add_nodes('idling', shape: 'ellipse')
+    @edge = @graph.add_edges('parked', 'idling', label: 'ignite')
+  end
+
+  def test_should_return_generated_edge
+    refute_nil(@edge)
+  end
+
+  def test_should_use_specified_nodes
+    assert_equal('parked', @edge.node_one(false))
+    assert_equal('idling', @edge.node_two(false))
+  end
+
+  def test_should_use_specified_options
+    assert_equal('ignite', @edge['label'].to_s.gsub('"', ''))
+  end
+
+  def test_should_set_default_font
+    assert_equal('Arial', @edge['fontname'].to_s.gsub('"', ''))
+  end
+end

data/test/graph_nodes_test.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative 'test_helper'
+describe StateMachines::Graph do
+  def setup
+    @graph = StateMachines::Graph.new('test')
+    @node = @graph.add_nodes('parked', shape: 'ellipse')
+  end
+
+  def test_should_return_generated_node
+    refute_nil @node
+  end
+
+  def test_should_use_specified_name
+    assert_equal(@node, @graph.get_node('parked'))
+  end
+
+  def test_should_use_specified_options
+    assert_equal('ellipse', @node['shape'].to_s.gsub('"', ''))
+  end
+
+  def test_should_set_default_font
+    assert_equal('Arial', @node['fontname'].to_s.gsub('"', ''))
+  end
+end

data/test/graph_output_test.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative 'test_helper'
+describe StateMachines::Graph do
+  def setup
+    @graph_name = "test_#{rand(1_000_000)}"
+    @graph = StateMachines::Graph.new(@graph_name)
+    @graph.add_nodes('parked', shape: 'ellipse')
+    @graph.add_nodes('idling', shape: 'ellipse')
+    @graph.add_edges('parked', 'idling', label: 'ignite')
+    @graph.output
+  end
+
+  def test_should_save_file
+    assert File.exist?("doc/state_machines/#{@graph_name}.png")
+  end
+
+  def teardown
+    FileUtils.rm Dir["doc/state_machines/#{@graph_name}.png"]
+  end
+end

data/test/machine_class_drawing_test.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative 'test_helper'
+
+describe StateMachines::Machine do
+  def switch_file
+    File.expand_path("#{File.dirname(__FILE__)}/files/switch.rb")
+  end
+
+  def switch_machine
+    require switch_file
+    Switch.state_machines.values.first
+  end
+
+  def test_should_load_files
+    machine = switch_machine
+    assert(defined?(::Switch))
+    assert(machine)
+  end
+
+  def test_should_allow_path_and_format_to_be_customized
+    machine = switch_machine
+    output_path = File.dirname(__FILE__)
+    machine.draw(path: output_path, format: 'jpg')
+    assert(File.exist?("#{output_path}/#{Switch.name}_state.jpg"))
+    FileUtils.rm Dir["{.,#{output_path}}/#{Switch.name}_state.{jpg,png}"]
+  end
+end

data/test/machine_drawing_test.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require_relative 'test_helper'
+
+describe StateMachines::Graph do
+  def setup
+    @klass = Class.new do
+      def self.name
+        @name ||= "Vehicle_#{rand(1_000_000)}"
+      end
+    end
+
+    @machine = StateMachines::Machine.new(@klass, initial: :parked)
+    @machine.event :ignite do
+      transition parked: :idling
+    end
+  end
+
+  def test_should_raise_exception_if_invalid_option_specified
+    assert_raises(ArgumentError) { @machine.draw(invalid: true) }
+  end
+
+  def test_should_save_file_with_class_name_by_default
+    @machine.draw
+    assert File.exist?("doc/state_machines/#{@klass.name}_state.png"), 'Failed to save file with class name'
+  end
+
+  def test_should_allow_base_name_to_be_customized
+    name = "@machine_#{rand(1_000_000)}"
+    @machine.draw(name: name)
+    @path = "doc/state_@machines/#{name}.png"
+  end
+
+  def test_should_allow_format_to_be_customized
+    @machine.draw(format: 'jpg')
+    @path = "doc/state_machines/#{@klass.name}_state.jpg"
+    assert File.exist?(@path), 'allow format to be custom'
+  end
+
+  def test_should_allow_path_to_be_customized
+    @machine.draw(path: "#{File.dirname(__FILE__)}/")
+    @path = "#{File.dirname(__FILE__)}/#{@klass.name}_state.png"
+    assert(File.exist?(@path))
+  end
+
+  def test_should_allow_orientation_to_be_landscape
+    @graph = @machine.draw(orientation: 'landscape')
+    assert_equal(@graph['rankdir'].to_s.gsub('"', ''), 'LR')
+  end
+
+  def test_should_allow_orientation_to_be_portrait
+    @graph = @machine.draw(orientation: 'portrait')
+    assert_equal(@graph['rankdir'].to_s.gsub('"', ''), 'TB')
+  end
+
+  def test_should_allow_human_names_to_be_displayed
+    @machine.event :ignite, human_name: 'Ignite'
+    @machine.state :parked, human_name: 'Parked'
+    @machine.state :idling, human_name: 'Idling'
+    @graph = @machine.draw(human_names: true)
+
+    parked_node = @graph.get_node('parked')
+    assert_equal(parked_node['label'].to_s.gsub('"', ''), 'Parked')
+
+    idling_node = @graph.get_node('idling')
+    assert_equal(idling_node['label'].to_s.gsub('"', ''), 'Idling')
+  end
+
+  def teardown
+    FileUtils.rm Dir[@path || "doc/state_@machines/#{@klass.name}_state.png"]
+  end
+end

data/test/machine_drawing_with_dynamic_states_test.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative 'test_helper'
+
+describe StateMachines::Graph do
+  def setup
+    @klass = Class.new do
+      def self.name
+        @name ||= "Vehicle_#{rand(1_000_000)}"
+      end
+    end
+
+    @machine = StateMachines::Machine.new(@klass, initial: :parked)
+    @machine.event :activate do
+      transition parked: :idling
+    end
+
+    @machine.state :idling, value: -> { Time.now }
+
+    @graph = @machine.draw
+  end
+
+  def test_should_draw_all_states
+    assert(@graph.node_count, 3)
+  end
+
+  def test_should_draw_all_events
+    assert(@graph.edge_count, 2)
+  end
+
+  def test_should_draw_machine
+    assert(File.exist?("doc/state_machines/#{@klass.name}_state.png"))
+  end
+
+  def teardown
+    FileUtils.rm Dir["doc/state_machines/#{@klass.name}_state.png"]
+  end
+end

data/test/machine_drawing_with_integer_states_test.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative 'test_helper'
+
+describe StateMachines::Graph do
+  def setup
+    @klass = Class.new do
+      def self.name
+        @name ||= "Vehicle_#{rand(1_000_000)}"
+      end
+    end
+
+    @machine = StateMachines::Machine.new(@klass, :state_id, initial: :parked)
+    @machine.event :ignite do
+      transition parked: :idling
+    end
+    @machine.state :parked, value: 1
+    @machine.state :idling, value: 2
+
+    @graph = @machine.draw
+  end
+
+  def test_should_draw_all_states
+    assert_equal(@graph.node_count, 3)
+  end
+
+  def test_should_draw_all_events
+    assert_equal(@graph.edge_count, 2)
+  end
+
+  def test_should_draw_machine
+    assert(File.exist?("doc/state_machines/#{@klass.name}_state_id.png"))
+  end
+
+  def teardown
+    assert(File.exist?("doc/state_machines/#{@klass.name}_state_id.png"))
+  end
+end