circulator 2.1.3 → 2.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bdd2e4e17046d72b53d25ea469b8f037316abf74cb7a34fe010091ff4f8b5bfa
-  data.tar.gz: 879a93ab33bb08c07fb6239ce490c5d900272cbd3cd03a65c66516f95439499e
+  metadata.gz: 9126192a7ce18956bc8c27842e52765dac25e9436e322ad259100e5138a5b97f
+  data.tar.gz: f1e15524d5806a3f0b0455bd006e8ba5e3914b13e046ab0d2acd1dbcb897ea27
 SHA512:
-  metadata.gz: 910cd9755d9b9c02996d9d38329082733d019019151c19bc839663893e3523a6c64be9149485317bc7a0979f10223d15c4e0bb34ae0a9942f30d1c473acf8378
-  data.tar.gz: a98cad092d4da49cf93c38db6462489730061c38439f9825e2d2378ef58def38d3db243784c570f50697704442d271d8ac3aa0b1eddd5147e7f4a65b2a346c8a
+  metadata.gz: 03ad68c5d43c45fddf1b7d5c3f84dd845363b2bf8cc1a881463efbd1b1e43d233e196e965dae157726b2ac0b90066d9ec05087f12339667ffd1e9effe0213e54
+  data.tar.gz: 7590c58b27a608f4d49f6041c9fed8a4fd5a05526cd5c36eba40a12346ce5a63cd6f9f0a6253c48ec6aa7405e9e4b5ed8121fae276404a1a32f4587118453c2f

data/CHANGELOG.md

@@ -5,12 +5,24 @@ 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
+## [2.1.4] - 2025-11-03
 
-### Fixed
+### Added
 
-- Ignore nil states in predicate methods (73c74c2)
+- Symbol-based allow_if support (a96b794)
+- Documentation for symbol-based allow_if (d3befc1)
+- available_flows method with guard and argument support (122e2ab)
+- available_flow? predicate method (122e2ab)
+- Documentation for query methods (a75507e)
 
-### Added
+### Changed
+
+- Validate symbol allow_if at definition time (392eac5)
+
+### Removed
+
+- Redundant respond_to? check (40ff669)
+
+### Fixed
 
-- Attribute predicate methods and documentation (8f9cc33)
+- DOT syntax error for states ending with ? (65b503e)

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

@@ -83,14 +83,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
 

data/lib/circulator/version.rb

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

data/lib/circulator.rb

@@ -209,6 +209,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 +277,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.4
 platform: ruby
 authors:
 - Jim Gay