circulator 2.1.3 → 2.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bdd2e4e17046d72b53d25ea469b8f037316abf74cb7a34fe010091ff4f8b5bfa
-  data.tar.gz: 879a93ab33bb08c07fb6239ce490c5d900272cbd3cd03a65c66516f95439499e
+  metadata.gz: 4c511772e424334259794bfff3d3507e5740fc98f0a130c66bf1d77a41862f6a
+  data.tar.gz: 7ee239ac23cbd6998a6d1689f8d6729983b42a6d6081e092465483ee19013107
 SHA512:
-  metadata.gz: 910cd9755d9b9c02996d9d38329082733d019019151c19bc839663893e3523a6c64be9149485317bc7a0979f10223d15c4e0bb34ae0a9942f30d1c473acf8378
-  data.tar.gz: a98cad092d4da49cf93c38db6462489730061c38439f9825e2d2378ef58def38d3db243784c570f50697704442d271d8ac3aa0b1eddd5147e7f4a65b2a346c8a
+  metadata.gz: 63e6165e93a276d89ac6c469c3e8b5db41e6b184cde3290a9ff1332992e7f27a06cf1cd8f8b93c32100986c27be3761d0cfbc9ef7c69414b0cd379f32813c018
+  data.tar.gz: 586cdd39db8b98b10465e84c02de948a44f39c556ae270ea6a68ea8f90ca8c0b61af37917419dfe599e39e882584101169f932671996edbeeb97d6e9debe806d

data/CHANGELOG.md

@@ -5,12 +5,10 @@ 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.3] - 2025-10-27
-
-### Fixed
-
-- Ignore nil states in predicate methods (73c74c2)
+## [2.1.5] - 2025-11-15
 
 ### Added
 
-- Attribute predicate methods and documentation (8f9cc33)
+- Circulator.extension to define changes to existing state machines. (0f0a50f)
+- Circulator.default_flow_proc to allow for custom storage objects. (7ddc442)
+- Test support for custom flows storage with libraries like Contours::BlendedHash. (c7f1f26)

data/README.md

@@ -103,10 +103,36 @@ order.status_pending?     # => false
 
 These predicate methods work with both symbol and string values, automatically converting strings to symbols for comparison.
 
+#### Query Available Actions
+
+Circulator provides methods to query which actions are available from the current state:
+
+```ruby
+order.status = :pending
+
+# Get all available actions
+order.available_flows(:status)  # => [:approve, :reject]
+
+# Check if a specific action is available
+order.available_flow?(:status, :approve)  # => true
+order.available_flow?(:status, :ship)     # => false
+```
+
+These methods respect all `allow_if` conditions and can accept arguments to pass through to guard conditions:
+
+```ruby
+# With conditional guards
+order.available_flow?(:status, :approve, level: 5)  # => true
+```
+
 ### Advanced Features
 
 #### Conditional Transitions with Guards
 
+You can control when transitions are allowed using the `allow_if` option. Circulator supports three types of guards:
+
+**Proc-based guards** evaluate a block of code:
+
 ```ruby
 class Document
   extend Circulator
@@ -125,7 +151,29 @@ class Document
 end
 ```
 
-#### Nested State Dependencies
+**Symbol-based guards** call a method on the object:
+
+```ruby
+class Document
+  extend Circulator
+
+  attr_accessor :state, :reviewed_by
+
+  circulator :state do
+    state :draft do
+      action :publish, to: :published, allow_if: :ready_to_publish?
+    end
+  end
+
+  def ready_to_publish?
+    reviewed_by.present?
+  end
+end
+```
+
+This is equivalent to the proc-based approach but cleaner when you have a dedicated method for the condition.
+
+**Hash-based guards** check the state of another attribute:
 
 You can make one state machine depend on another using hash-based `allow_if`:
 

data/lib/circulator/dot.rb

@@ -6,6 +6,14 @@ module Circulator
   class Dot < Diagram
     private
 
+    def quote_node_name(name)
+      if name.end_with?("?")
+        "\"#{name}\""
+      else
+        name
+      end
+    end
+
     def flows_output(flows_data, output)
       if flows_data.size == 1
         # Single flow: no grouping needed
@@ -27,7 +35,8 @@ module Circulator
             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];"
+            quoted_name = quote_node_name(prefixed_name)
+            output << "    #{quoted_name} [label=\"#{state_label}\", shape=circle];"
           end
 
           output << "  }"
@@ -43,7 +52,9 @@ module Circulator
             # 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]}\"];"
+            quoted_from = quote_node_name(prefixed_from)
+            quoted_to = quote_node_name(prefixed_to)
+            output << "  #{quoted_from} -> #{quoted_to} [label=\"#{transition[:label]}\"];"
           end
         end
       end
@@ -67,7 +78,8 @@ module Circulator
       output << "  // States"
       states.sort_by { |s| s.to_s }.each do |state|
         state_label = state.nil? ? "nil" : state.to_s
-        output << "  #{state_label} [shape=circle];"
+        quoted_name = quote_node_name(state_label)
+        output << "  #{quoted_name} [shape=circle];"
       end
     end
 
@@ -77,7 +89,9 @@ module Circulator
       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
-        output << "  #{from_label} -> #{to_label} [label=\"#{transition[:label]}\"];"
+        quoted_from = quote_node_name(from_label)
+        quoted_to = quote_node_name(to_label)
+        output << "  #{quoted_from} -> #{quoted_to} [label=\"#{transition[:label]}\"];"
       end
     end
 

data/lib/circulator/flow.rb

@@ -2,13 +2,19 @@
 
 module Circulator
   class Flow
-    def initialize(klass, attribute_name, states = Set.new, &block)
+    def initialize(klass, attribute_name, states = Set.new, extension: false, flows_proc: Circulator.default_flow_proc, &block)
       @klass = klass
       @attribute_name = attribute_name
       @states = states
       @no_action = ->(attribute_name, action) { raise "No action found for the current state of #{attribute_name} (#{send(attribute_name)}): #{action}" }
-      @transition_map = {}
-      instance_eval(&block)
+      @flows_proc = flows_proc
+      @transition_map = flows_proc.call
+
+      # Execute the main flow block
+      instance_eval(&block) if block
+
+      # Apply any registered extensions (unless explicitly disabled)
+      apply_extensions unless extension
     end
     attr_reader :transition_map
 
@@ -28,7 +34,7 @@ module Circulator
         validate_allow_if(allow_if)
       end
 
-      @transition_map[name] ||= {}
+      @transition_map[name] ||= @flows_proc.call
       selected_state = (from == :__not_specified__) ? @current_state : from
 
       # Handle nil case specially - convert to [nil] instead of []
@@ -48,8 +54,10 @@ module Circulator
           @states.add(to_state)
         end
 
-        @transition_map[name][from_state] = {to:, block:}
-        @transition_map[name][from_state][:allow_if] = allow_if if allow_if
+        # Build transition data hash with all keys at once
+        transition_data = {to:, block:}
+        transition_data[:allow_if] = allow_if if allow_if
+        @transition_map[name][from_state] = transition_data
       end
     end
 
@@ -83,14 +91,21 @@ module Circulator
     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}"
+      case allow_if
+      in Proc
+        # Valid, no additional validation needed
+      in Symbol
+        validate_symbol_allow_if(allow_if)
+      in Hash
+        validate_hash_allow_if(allow_if)
+      else
+        raise ArgumentError, "allow_if must be a Proc, Hash, or Symbol, got: #{allow_if.class}"
       end
+    end
 
-      # If it's a Hash, validate the structure
-      if allow_if.is_a?(Hash)
-        validate_hash_allow_if(allow_if)
+    def validate_symbol_allow_if(method_name)
+      unless @klass.method_defined?(method_name)
+        raise ArgumentError, "allow_if references undefined method :#{method_name} on #{@klass}"
       end
     end
 
@@ -125,5 +140,33 @@ module Circulator
         raise ArgumentError, "allow_if references invalid states #{invalid_states.inspect} for :#{attribute_name}. Valid states: #{referenced_states.to_a.inspect}"
       end
     end
+
+    def apply_extensions
+      # Look up extensions for this class and attribute
+      class_name = if @klass.is_a?(Class)
+        @klass.name || @klass.to_s
+      else
+        Circulator.model_key(@klass)
+      end
+      key = "#{class_name}:#{@attribute_name}"
+      extensions = Circulator.extensions[key]
+
+      # Apply each extension by creating a new Flow and merging its transition_map
+      extensions.each do |extension_block|
+        extension_flow = Flow.new(@klass, @attribute_name, @states, extension: true, flows_proc: @flows_proc, &extension_block)
+        extension_flow.transition_map.each do |action, transitions|
+          @transition_map[action] = if @transition_map[action]
+            @transition_map[action].merge(transitions)
+          else
+            transitions
+          end
+        end
+
+        # Merge states from extension
+        extension_flow.instance_variable_get(:@states).each do |state|
+          @states.add(state)
+        end
+      end
+    end
   end
 end

data/lib/circulator/version.rb

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

data/lib/circulator.rb

@@ -2,6 +2,32 @@ require "circulator/version"
 require "circulator/flow"
 
 module Circulator
+  # Global registry for extensions
+  @extensions = Hash.new { |h, k| h[k] = [] }
+
+  @default_flow_proc = ::Hash.method(:new)
+  class << self
+    attr_reader :extensions
+    attr_reader :default_flow_proc
+
+    # Register an extension for a specific class and attribute
+    #
+    # Example:
+    #
+    #   Circulator.extension(:Document, :status) do
+    #     state :pending do
+    #       action :send_to_legal, to: :legal_review
+    #     end
+    #   end
+    #
+    # Extensions are automatically applied when the class defines its flow
+    def extension(class_name, attribute_name, &block)
+      raise ArgumentError, "Block required for extension" unless block_given?
+
+      key = "#{class_name}:#{attribute_name}"
+      @extensions[key] << block
+    end
+  end
   # Declare a flow for an attribute.
   #
   # Specify the attribute to be used for states and actions.
@@ -125,11 +151,12 @@ module Circulator
   #  test_object.flow(:unknown, :status, "signal")
   #  # Will raise an UnhandledSignalError
   #
-  def flow(attribute_name, model: to_s, &block)
-    @flows ||= {}
+  def flow(attribute_name, model: to_s, flows_proc: Circulator.default_flow_proc, &block)
+    @flows ||= flows_proc.call
     model_key = Circulator.model_key(model)
-    @flows[model_key] ||= {}
-    @flows[model_key][attribute_name] = Flow.new(self, attribute_name, &block)
+    @flows[model_key] ||= flows_proc.call
+    # Pass the flows_proc to Flow so it can create transition_maps of the same type
+    @flows[model_key][attribute_name] = Flow.new(self, attribute_name, flows_proc:, &block)
 
     flow_module = ancestors.find { |ancestor|
       ancestor.name.to_s =~ /FlowMethods/
@@ -209,6 +236,9 @@ module Circulator
 
           # Return early if current state is not in the valid states
           return unless valid_states_array.include?(current_state)
+        elsif transition[:allow_if].is_a?(Symbol)
+          # Handle symbol-based allow_if (method name)
+          return unless flow_target.send(transition[:allow_if])
         else
           # Handle proc-based allow_if (original behavior)
           return unless flow_target.instance_exec(*args, **kwargs, &transition[:allow_if])
@@ -274,10 +304,62 @@ module Circulator
       end
     end
 
+    # Get available actions for an attribute based on current state
+    #
+    # Example:
+    #
+    #   test_object.available_flows(:status)
+    #   # => [:approve, :reject]
+    def available_flows(attribute, *args, **kwargs)
+      model_key = Circulator.model_key(self)
+      flow = flows.dig(model_key, attribute)
+      return [] unless flow
+
+      current_value = send(attribute)
+      current_state = current_value.respond_to?(:to_sym) ? current_value.to_sym : current_value
+
+      flow.transition_map.select do |action, transitions|
+        transition = transitions[current_state]
+        next false unless transition
+
+        # Check allow_if condition if present
+        if transition[:allow_if]
+          check_allow_if(transition[:allow_if], *args, **kwargs)
+        else
+          true
+        end
+      end.keys
+    end
+
+    # Check if a specific action is available for an attribute
+    #
+    # Example:
+    #
+    #   test_object.available_flow?(:status, :approve)
+    #   # => true
+    def available_flow?(attribute, action, *args, **kwargs)
+      available_flows(attribute, *args, **kwargs).include?(action)
+    end
+
     private
 
     def flows
       self.class.flows
     end
+
+    def check_allow_if(allow_if, *args, **kwargs)
+      case allow_if
+      when Hash
+        attribute_name, valid_states = allow_if.first
+        current_state = send(attribute_name)
+        current_state = current_state.to_sym if current_state.respond_to?(:to_sym)
+        valid_states_array = Array(valid_states).map { |s| s.respond_to?(:to_sym) ? s.to_sym : s }
+        valid_states_array.include?(current_state)
+      when Symbol
+        send(allow_if, *args, **kwargs)
+      else # Proc
+        instance_exec(*args, **kwargs, &allow_if)
+      end
+    end
   end
 end

metadata

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