circulator 2.1.0 → 2.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a33499a72d0661bf32e27e39213e4b0193f292eef8537c1946f0eb139e751a91
-  data.tar.gz: 6c3fa67b66bef192886a17cc9d756cb491bce6509127b43b87e7f5ca74347ef4
+  metadata.gz: 1a3d83bc194cf2440d13e088b1b23e72cf3ec89071ae9d046d575a7e5d1014c7
+  data.tar.gz: 4c1afec2234a2edf3675048519aac13e4b64f2c8bbb08b98387603fc5f354ea8
 SHA512:
-  metadata.gz: 3755e25bcb3a1b34ba3768e8e3b501489dd7827ad9c1695b7365c2ffee9cbf9160181e2bd7226ba49e5c76d1763811e425beef4a0250a28811f22e57f970df98
-  data.tar.gz: 0c970bbeca86d6835911ae4ec7369585a14a9815ff6fc4fcdf28886ae556f0fc3b3d1be97fc301a45799bb5cc3b702681b3160f0072489a5eb96cfdb222fd225
+  metadata.gz: a5bf023b56fe2f8352fbb2fadce2c8a29cb9a47cfd5b011c80c098646696b9dcd5735c2b027c8f4a126c285005f11c8b46e9c009ac8ad243df3e1bc8a5979523
+  data.tar.gz: e4f99d8cd3e1cdbf87a15eb0b588ffc778f0fdf412c897fb5bf6796ff1295351fcf542c6ea80d1f883b1c3fa6afd817925ecddbda39ac1e16ffc9a59665754cb

data/CHANGELOG.md

@@ -5,8 +5,8 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [2.1.0] - 2025-10-02
+## [2.1.2] - 2025-10-17
 
 ### Added
 
-- Configure directory for generating diagrams, defaulting to "docs"
+- Hash-based allow_if for nested state dependencies (411a6b5)

data/README.md

@@ -8,6 +8,7 @@ A lightweight and flexible state machine implementation for Ruby that allows you
 - **Flexible DSL**: Intuitive syntax for defining states and transitions
 - **Dynamic Method Generation**: Automatically creates helper methods for state transitions
 - **Conditional Transitions**: Support for guards and conditional logic
+- **Nested State Dependencies**: State machines can depend on the state of other attributes
 - **Transition Callbacks**: Execute code before, during, or after transitions
 - **Multiple State Machines**: Define multiple independent state machines per class
 - **Framework Agnostic**: Works with plain Ruby objects, no Rails or ActiveRecord required
@@ -93,6 +94,43 @@ class Document
 end
 ```
 
+#### Nested State Dependencies
+
+You can make one state machine depend on another using hash-based `allow_if`:
+
+```ruby
+class Document
+  extend Circulator
+
+  attr_accessor :status, :review_status
+
+  # Review must be completed first
+  flow :review_status do
+    state :pending do
+      action :approve, to: :approved
+    end
+    state :approved
+  end
+
+  # Document status depends on review status
+  flow :status do
+    state :draft do
+      # Can only publish if review is approved
+      action :publish, to: :published, allow_if: {review_status: [:approved]}
+    end
+  end
+end
+
+doc = Document.new
+doc.status = :draft
+doc.review_status = :pending
+
+doc.status_publish  # => blocked, status remains :draft
+
+doc.review_status_approve  # => :approved
+doc.status_publish         # => :published ✓
+```
+
 #### Dynamic Destination States
 
 ```ruby

data/exe/circulator-diagram

@@ -8,7 +8,7 @@ require_relative "../lib/circulator/dot"
 require_relative "../lib/circulator/plantuml"
 
 # Parse command-line options
-options = {format: "dot", require: nil, directory: "docs"}
+options = {format: "dot", require: nil, directory: "docs", separate: false}
 parser = OptionParser.new do |opts|
   opts.banner = "Usage: circulator-diagram MODEL_NAME [options]"
   opts.separator ""
@@ -27,6 +27,10 @@ parser = OptionParser.new do |opts|
     options[:directory] = directory
   end
 
+  opts.on("-s", "--separate", "Generate separate diagram files for each flow attribute") do
+    options[:separate] = true
+  end
+
   opts.on("-r", "--require FILE", "Require a file before loading the model (e.g., config/environment)") do |file|
     options[:require] = file
   end
@@ -84,7 +88,7 @@ rescue NameError
   exit 1
 end
 
-# Generate diagram file
+# Generate diagram file(s)
 begin
   generator = case options[:format]
   when "plantuml"
@@ -93,9 +97,7 @@ begin
     Circulator::Dot.new(model_class)
   end
 
-  content = generator.generate
-
-  # Determine output filename and extension
+  # Determine base output filename and extension
   # Convert namespaced class names to directory paths
   # Something::Other becomes something/other
   class_name = model_class.name || "diagram"
@@ -104,30 +106,62 @@ begin
   }
   base_name = path_parts.join("/")
 
-  if options[:format] == "plantuml"
-    # Use model class name for PlantUML files
-    output_file = File.join(options[:directory], "#{base_name}.puml")
-
-    # Create directory if needed
-    dir = File.dirname(output_file)
-    FileUtils.mkdir_p(dir) unless File.exist?(dir)
-
-    File.write(output_file, content)
-    puts "Generated PlantUML file: #{output_file}"
-    puts "To create an image, run:"
-    puts "  plantuml #{output_file}"
+  if options[:separate]
+    # Generate separate diagram file for each flow attribute
+    diagrams = generator.generate_separate
+    extension = (options[:format] == "plantuml") ? ".puml" : ".dot"
+
+    diagrams.each do |attribute_name, content|
+      # Create filename with attribute name
+      output_file = File.join(options[:directory], "#{base_name}_#{attribute_name}#{extension}")
+
+      # Create directory if needed
+      dir = File.dirname(output_file)
+      FileUtils.mkdir_p(dir) unless File.exist?(dir)
+
+      File.write(output_file, content)
+      puts "Generated #{options[:format]} file: #{output_file}"
+    end
+
+    puts ""
+    puts "To create images, run:"
+    if options[:format] == "plantuml"
+      puts "  plantuml #{File.join(options[:directory], "#{base_name}_*#{extension}")}"
+    else
+      diagrams.keys.each do |attribute_name|
+        output_file = File.join(options[:directory], "#{base_name}_#{attribute_name}#{extension}")
+        puts "  dot -Tpng #{output_file} -o #{File.join(options[:directory], "#{base_name}_#{attribute_name}")}.png"
+      end
+    end
   else
-    # Use model class name for DOT files
-    output_file = File.join(options[:directory], "#{base_name}.dot")
-
-    # Create directory if needed
-    dir = File.dirname(output_file)
-    FileUtils.mkdir_p(dir) unless File.exist?(dir)
-
-    File.write(output_file, content)
-    puts "Generated DOT file: #{output_file}"
-    puts "To create an image, run:"
-    puts "  dot -Tpng #{output_file} -o #{File.join(options[:directory], base_name)}.png"
+    # Generate single combined diagram file
+    content = generator.generate
+
+    if options[:format] == "plantuml"
+      # Use model class name for PlantUML files
+      output_file = File.join(options[:directory], "#{base_name}.puml")
+
+      # Create directory if needed
+      dir = File.dirname(output_file)
+      FileUtils.mkdir_p(dir) unless File.exist?(dir)
+
+      File.write(output_file, content)
+      puts "Generated PlantUML file: #{output_file}"
+      puts "To create an image, run:"
+      puts "  plantuml #{output_file}"
+    else
+      # Use model class name for DOT files
+      output_file = File.join(options[:directory], "#{base_name}.dot")
+
+      # Create directory if needed
+      dir = File.dirname(output_file)
+      FileUtils.mkdir_p(dir) unless File.exist?(dir)
+
+      File.write(output_file, content)
+      puts "Generated DOT file: #{output_file}"
+      puts "To create an image, run:"
+      puts "  dot -Tpng #{output_file} -o #{File.join(options[:directory], base_name)}.png"
+    end
   end
 
   exit 0

data/lib/circulator/diagram.rb

@@ -20,12 +20,14 @@ module Circulator
       output = []
       output << header
 
-      # Collect all states and transitions
-      states = Set.new
-      transitions = []
+      # Collect states and transitions grouped by attribute
+      flows_data = []
 
       @flows.each do |model_key, attribute_flows|
         attribute_flows.each do |attribute_name, flow|
+          states = Set.new
+          transitions = []
+
           # Extract states and transitions from the flow
           flow.transition_map.each do |action, state_transitions|
             state_transitions.each do |from_state, transition_info|
@@ -41,19 +43,68 @@ module Circulator
               end
             end
           end
+
+          flows_data << {
+            attribute_name: attribute_name,
+            states: states,
+            transitions: transitions
+          }
         end
       end
 
-      # Output state nodes
-      states_output(states, output)
-
-      # Output transition edges
-      transitions_output(transitions, output)
+      # Output flows (grouped or combined based on subclass implementation)
+      flows_output(flows_data, output)
 
       output << footer
       output.join("\n") + "\n"
     end
 
+    # Generate separate diagrams for each flow attribute
+    # Returns a hash mapping attribute_name => diagram_content
+    def generate_separate
+      result = {}
+
+      @flows.each do |model_key, attribute_flows|
+        attribute_flows.each do |attribute_name, flow|
+          states = Set.new
+          transitions = []
+
+          # Extract states and transitions from the flow
+          flow.transition_map.each do |action, state_transitions|
+            state_transitions.each do |from_state, transition_info|
+              states.add(from_state)
+
+              to_state = transition_info[:to]
+              if to_state.respond_to?(:call)
+                states.add(:"?")
+                transitions << dynamic_transition(action, from_state, :"?")
+              else
+                states.add(to_state)
+                transitions << standard_transition(action, from_state, to_state, conditional: transition_info[:allow_if])
+              end
+            end
+          end
+
+          # Generate diagram for this flow only
+          output = []
+          output << header_for_attribute(attribute_name)
+
+          flows_data = [{
+            attribute_name: attribute_name,
+            states: states,
+            transitions: transitions
+          }]
+
+          flows_output(flows_data, output)
+          output << footer
+
+          result[attribute_name] = output.join("\n") + "\n"
+        end
+      end
+
+      result
+    end
+
     private
 
     def graph_name
@@ -74,15 +125,15 @@ module Circulator
       raise NotImplementedError, "Subclasses must implement #{__method__}"
     end
 
-    def footer
+    def header_for_attribute(attribute_name)
       raise NotImplementedError, "Subclasses must implement #{__method__}"
     end
 
-    def transitions_output(transitions, output)
+    def footer
       raise NotImplementedError, "Subclasses must implement #{__method__}"
     end
 
-    def states_output(states, output)
+    def flows_output(flows_data, output)
       raise NotImplementedError, "Subclasses must implement #{__method__}"
     end
 

data/lib/circulator/dot.rb

@@ -6,6 +6,49 @@ module Circulator
   class Dot < Diagram
     private
 
+    def flows_output(flows_data, output)
+      if flows_data.size == 1
+        # Single flow: no grouping needed
+        flow = flows_data.first
+        states_output(flow[:states], output)
+        transitions_output(flow[:transitions], output)
+      else
+        # Multiple flows: use subgraph clusters
+        flows_data.each_with_index do |flow, index|
+          output << ""
+          output << "  subgraph cluster_#{index} {"
+          output << "    label=\":#{flow[:attribute_name]}\";"
+          output << "    style=dashed;"
+          output << "    color=blue;"
+          output << ""
+
+          # Output states within this cluster
+          flow[:states].sort_by(&:to_s).each do |state|
+            state_label = state.nil? ? "nil" : state.to_s
+            # Prefix state names with attribute to avoid conflicts
+            prefixed_name = "#{flow[:attribute_name]}_#{state_label}"
+            output << "    #{prefixed_name} [label=\"#{state_label}\", shape=circle];"
+          end
+
+          output << "  }"
+        end
+
+        # Output all transitions after clusters
+        output << ""
+        output << "  // Transitions"
+        flows_data.each do |flow|
+          flow[:transitions].sort_by { |t| [t[:from].to_s, t[:to].to_s, t[:label]] }.each do |transition|
+            from_label = transition[:from].nil? ? "nil" : transition[:from].to_s
+            to_label = transition[:to].nil? ? "nil" : transition[:to].to_s
+            # Use prefixed names
+            prefixed_from = "#{flow[:attribute_name]}_#{from_label}"
+            prefixed_to = "#{flow[:attribute_name]}_#{to_label}"
+            output << "  #{prefixed_from} -> #{prefixed_to} [label=\"#{transition[:label]}\"];"
+          end
+        end
+      end
+    end
+
     # def graph_name
     #   # Use the model class name if available, otherwise use the model key
     #   class_name = @model_class.name
@@ -45,6 +88,14 @@ module Circulator
       DOT
     end
 
+    def header_for_attribute(attribute_name)
+      class_name = @model_class.name || "diagram"
+      <<~DOT
+        digraph "#{class_name} :#{attribute_name} flow" {
+          rankdir=LR;
+      DOT
+    end
+
     def footer
       "}"
     end

data/lib/circulator/flow.rb

@@ -23,6 +23,11 @@ module Circulator
     def action(name, to:, from: :__not_specified__, allow_if: nil, &block)
       raise "You must be in a state block or have a `from` option to declare an action" unless defined?(@current_state) || from != :__not_specified__
 
+      # Validate allow_if parameter
+      if allow_if
+        validate_allow_if(allow_if)
+      end
+
       @transition_map[name] ||= {}
       selected_state = (from == :__not_specified__) ? @current_state : from
 
@@ -36,6 +41,13 @@ module Circulator
       states_to_process.each do |from_state|
         from_state = from_state.to_sym if from_state.respond_to?(:to_sym)
         @states.add(from_state)
+
+        # Add the target state to @states if it's not a callable
+        unless to.respond_to?(:call)
+          to_state = to.respond_to?(:to_sym) ? to.to_sym : to
+          @states.add(to_state)
+        end
+
         @transition_map[name][from_state] = {to:, block:}
         @transition_map[name][from_state][:allow_if] = allow_if if allow_if
       end
@@ -67,5 +79,51 @@ module Circulator
         @no_action
       end
     end
+
+    private
+
+    def validate_allow_if(allow_if)
+      # Must be either a Proc or a Hash
+      unless allow_if.is_a?(Proc) || allow_if.is_a?(Hash)
+        raise ArgumentError, "allow_if must be a Proc or Hash, got: #{allow_if.class}"
+      end
+
+      # If it's a Hash, validate the structure
+      if allow_if.is_a?(Hash)
+        validate_hash_allow_if(allow_if)
+      end
+    end
+
+    def validate_hash_allow_if(allow_if_hash)
+      # Must have exactly one key
+      if allow_if_hash.size != 1
+        raise ArgumentError, "allow_if hash must contain exactly one attribute, got: #{allow_if_hash.keys.inspect}"
+      end
+
+      attribute_name, valid_states = allow_if_hash.first
+
+      # Convert attribute name to symbol
+      attribute_name = attribute_name.to_sym if attribute_name.respond_to?(:to_sym)
+
+      # Get model_key from the class name string, not the Class object
+      model_key = Circulator.model_key(@klass.to_s)
+      unless @klass.flows&.dig(model_key, attribute_name)
+        available_flows = @klass.flows&.dig(model_key)&.keys || []
+        raise ArgumentError, "allow_if references undefined flow attribute :#{attribute_name}. Available flows: #{available_flows.inspect}"
+      end
+
+      # Get the states from the referenced flow
+      referenced_flow = @klass.flows.dig(model_key, attribute_name)
+      referenced_states = referenced_flow.instance_variable_get(:@states)
+
+      # Convert valid_states to array of symbols
+      valid_states_array = Array(valid_states).map { |s| s.respond_to?(:to_sym) ? s.to_sym : s }
+
+      # Check if all specified states exist in the referenced flow
+      invalid_states = valid_states_array - referenced_states.to_a
+      if invalid_states.any?
+        raise ArgumentError, "allow_if references invalid states #{invalid_states.inspect} for :#{attribute_name}. Valid states: #{referenced_states.to_a.inspect}"
+      end
+    end
   end
 end

data/lib/circulator/plantuml.rb

@@ -6,9 +6,53 @@ module Circulator
   class PlantUml < Diagram
     private
 
-    # def graph_name
-    #   @model_class.name || "diagram"
-    # end
+    def flows_output(flows_data, output)
+      if flows_data.size == 1
+        # Single flow: no grouping needed
+        flow = flows_data.first
+        states_output(flow[:states], output)
+        transitions_output(flow[:transitions], output)
+      else
+        # Multiple flows: use composite states (state containers) with visible labels
+        flows_data.each do |flow|
+          output << ""
+          output << "state \":#{flow[:attribute_name]}\" as #{flow[:attribute_name]}_group {"
+
+          # Output states for this flow
+          flow[:states].reject(&:nil?).sort_by(&:to_s).each do |state|
+            # Replace characters that PlantUML doesn't like in identifiers
+            safe_state = state.to_s.gsub("?", "unknown")
+            prefixed_name = "#{flow[:attribute_name]}_#{safe_state}"
+            output << "  state \"#{state}\" as #{prefixed_name}"
+          end
+
+          output << "}"
+        end
+
+        # Output all transitions after composite states
+        output << ""
+        flows_data.each do |flow|
+          flow[:transitions].sort_by { |t| [t[:from].to_s, t[:to].to_s, t[:label]] }.each do |transition|
+            from_label = transition[:from].nil? ? "[*]" : transition[:from].to_s
+            to_label = transition[:to].nil? ? "[*]" : transition[:to].to_s
+            # Use prefixed names for non-nil states
+            # Replace characters that PlantUML doesn't like in identifiers
+            safe_from = from_label.gsub("?", "unknown")
+            safe_to = to_label.gsub("?", "unknown")
+            prefixed_from = transition[:from].nil? ? "[*]" : "#{flow[:attribute_name]}_#{safe_from}"
+            prefixed_to = transition[:to].nil? ? "[*]" : "#{flow[:attribute_name]}_#{safe_to}"
+            output << "#{prefixed_from} --> #{prefixed_to} : #{transition[:label]}"
+
+            # Add note if present
+            if transition[:note]
+              output << "note on link"
+              output << "  #{transition[:note]}"
+              output << "end note"
+            end
+          end
+        end
+      end
+    end
 
     def header
       <<~PLANTUML
@@ -17,6 +61,14 @@ module Circulator
       PLANTUML
     end
 
+    def header_for_attribute(attribute_name)
+      class_name = @model_class.name || "diagram"
+      <<~PLANTUML
+        @startuml #{class_name}_#{attribute_name}
+        title #{class_name} :#{attribute_name} flow
+      PLANTUML
+    end
+
     def footer
       <<~PLANTUML
 
@@ -48,7 +100,13 @@ module Circulator
 
     def states_output(states, output)
       states.reject(&:nil?).sort_by(&:to_s).each do |state|
-        output << "state #{state}"
+        # Replace characters that PlantUML doesn't like in identifiers
+        safe_state = state.to_s.gsub("?", "unknown")
+        output << if safe_state != state.to_s
+          "state \"#{state}\" as #{safe_state}"
+        else
+          "state #{state}"
+        end
       end
     end
 
@@ -56,7 +114,10 @@ module Circulator
       transitions.sort_by { |t| [t[:from].to_s, t[:to].to_s, t[:label]] }.each do |transition|
         from_label = transition[:from].nil? ? "[*]" : transition[:from].to_s
         to_label = transition[:to].nil? ? "[*]" : transition[:to].to_s
-        output << "#{from_label} --> #{to_label} : #{transition[:label]}"
+        # Replace characters that PlantUML doesn't like in identifiers
+        safe_from = (from_label == "[*]") ? from_label : from_label.gsub("?", "unknown")
+        safe_to = (to_label == "[*]") ? to_label : to_label.gsub("?", "unknown")
+        output << "#{safe_from} --> #{safe_to} : #{transition[:label]}"
 
         # Add note if present
         if transition[:note]

data/lib/circulator/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Circulator
-  VERSION = "2.1.0"
+  VERSION = "2.1.2"
 end

data/lib/circulator.rb

@@ -129,7 +129,7 @@ module Circulator
     @flows ||= {}
     model_key = Circulator.model_key(model)
     @flows[model_key] ||= {}
-    @flows[model_key][attribute_name] = Flow.new(model, attribute_name, &block)
+    @flows[model_key][attribute_name] = Flow.new(self, attribute_name, &block)
 
     flow_module = ancestors.find { |ancestor|
       ancestor.name.to_s =~ /FlowMethods/
@@ -170,7 +170,23 @@ module Circulator
       end
 
       if transition[:allow_if]
-        return unless flow_target.instance_exec(*args, **kwargs, &transition[:allow_if])
+        # Handle hash-based allow_if (checking other attribute states)
+        if transition[:allow_if].is_a?(Hash)
+          attribute_name_to_check, valid_states = transition[:allow_if].first
+          current_state = flow_target.send(attribute_name_to_check)
+
+          # Convert current state to symbol if possible
+          current_state = current_state.to_sym if current_state.respond_to?(:to_sym)
+
+          # Convert valid_states to array of symbols
+          valid_states_array = Array(valid_states).map { |s| s.respond_to?(:to_sym) ? s.to_sym : s }
+
+          # Return early if current state is not in the valid states
+          return unless valid_states_array.include?(current_state)
+        else
+          # Handle proc-based allow_if (original behavior)
+          return unless flow_target.instance_exec(*args, **kwargs, &transition[:allow_if])
+        end
       end
 
       if transition[:block]

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: circulator
 version: !ruby/object:Gem::Version
-  version: 2.1.0
+  version: 2.1.2
 platform: ruby
 authors:
 - Jim Gay