circulator 2.1.2 → 2.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1a3d83bc194cf2440d13e088b1b23e72cf3ec89071ae9d046d575a7e5d1014c7
-  data.tar.gz: 4c1afec2234a2edf3675048519aac13e4b64f2c8bbb08b98387603fc5f354ea8
+  metadata.gz: 9126192a7ce18956bc8c27842e52765dac25e9436e322ad259100e5138a5b97f
+  data.tar.gz: f1e15524d5806a3f0b0455bd006e8ba5e3914b13e046ab0d2acd1dbcb897ea27
 SHA512:
-  metadata.gz: a5bf023b56fe2f8352fbb2fadce2c8a29cb9a47cfd5b011c80c098646696b9dcd5735c2b027c8f4a126c285005f11c8b46e9c009ac8ad243df3e1bc8a5979523
-  data.tar.gz: e4f99d8cd3e1cdbf87a15eb0b588ffc778f0fdf412c897fb5bf6796ff1295351fcf542c6ea80d1f883b1c3fa6afd817925ecddbda39ac1e16ffc9a59665754cb
+  metadata.gz: 03ad68c5d43c45fddf1b7d5c3f84dd845363b2bf8cc1a881463efbd1b1e43d233e196e965dae157726b2ac0b90066d9ec05087f12339667ffd1e9effe0213e54
+  data.tar.gz: 7590c58b27a608f4d49f6041c9fed8a4fd5a05526cd5c36eba40a12346ce5a63cd6f9f0a6253c48ec6aa7405e9e4b5ed8121fae276404a1a32f4587118453c2f

data/CHANGELOG.md

@@ -5,8 +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.2] - 2025-10-17
+## [2.1.4] - 2025-11-03
 
 ### Added
 
-- Hash-based allow_if for nested state dependencies (411a6b5)
+- 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)
+
+### Changed
+
+- Validate symbol allow_if at definition time (392eac5)
+
+### Removed
+
+- Redundant respond_to? check (40ff669)
+
+### Fixed
+
+- DOT syntax error for states ending with ? (65b503e)

data/README.md

@@ -6,7 +6,7 @@ A lightweight and flexible state machine implementation for Ruby that allows you
 
 - **Lightweight**: Minimal dependencies and simple implementation
 - **Flexible DSL**: Intuitive syntax for defining states and transitions
-- **Dynamic Method Generation**: Automatically creates helper methods for state transitions
+- **Dynamic Method Generation**: Automatically creates action methods for transitions and predicate methods for state checks
 - **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
@@ -72,10 +72,67 @@ order.status_ship     # => :shipped
 order.status_deliver  # => :delivered
 ```
 
+### Generated Methods
+
+Circulator automatically generates two types of helper methods for your state machines:
+
+#### Action Methods
+
+For each action defined in your state machine, Circulator creates a method that performs the transition:
+
+```ruby
+order.status_process  # Transitions from :pending to :processing
+order.status_cancel   # Transitions to :cancelled
+```
+
+#### State Predicate Methods
+
+For each state in your state machine, Circulator creates a predicate method to check the current state:
+
+```ruby
+order.status = :pending
+
+order.status_pending?     # => true
+order.status_processing?  # => false
+order.status_shipped?     # => false
+
+order.status_process
+order.status_processing?  # => true
+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
@@ -94,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`:
 
@@ -227,7 +306,7 @@ Circulator distinguishes itself from other Ruby state machine libraries through
 - **Minimal Magic**: Unlike AASM and state_machines, Circulator uses straightforward Ruby metaprogramming without complex DSL magic
 - **No Dependencies**: Works with plain Ruby objects without requiring Rails, ActiveRecord, or other frameworks
 - **Lightweight**: Smaller footprint compared to feature-heavy alternatives
-- **Clear Method Names**: Generated methods follow predictable naming patterns (`status_approve`, `priority_escalate`)
+- **Clear Method Names**: Generated methods follow predictable naming patterns (`status_approve`, `status_pending?`)
 - **Flexible Architecture**: Easy to extend and customize for specific needs
 
 ### When to Use Circulator

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.2"
+  VERSION = "2.1.4"
 end

data/lib/circulator.rb

@@ -145,12 +145,38 @@ module Circulator
       Circulator.methodize_name(model)
     end
 
+    states = Set.new
     @flows.dig(model_key, attribute_name).transition_map.each do |action, transitions|
+      transitions.each do |from_state, transition_data|
+        states.add(from_state)
+        # Add the 'to' state if it's not a callable
+        unless transition_data[:to].respond_to?(:call)
+          states.add(transition_data[:to])
+        end
+      end
       define_flow_method(attribute_name:, action:, transitions:, object:, owner: flow_module)
     end
+
+    # Define predicate methods for each state (skip nil)
+    states.each do |state|
+      next if state.nil?
+      define_state_method(attribute_name:, state:, object:, owner: flow_module)
+    end
   end
   alias_method :circulator, :flow
 
+  def define_state_method(attribute_name:, state:, object:, owner:)
+    object_attribute_method = [object, attribute_name, state].compact.join("_") << "?"
+    return if owner.method_defined?(object_attribute_method)
+
+    owner.define_method(object_attribute_method) do
+      current_value = send(attribute_name)
+      # Convert to symbol for comparison if possible
+      current_value = current_value.to_sym if current_value.respond_to?(:to_sym)
+      current_value == state
+    end
+  end
+
   def define_flow_method(attribute_name:, action:, transitions:, object:, owner:)
     object_attribute_method = [object, attribute_name, action].compact.join("_")
     raise ArgumentError, "Method already defined: #{object_attribute_method}" if owner.method_defined?(object_attribute_method)
@@ -183,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])
@@ -248,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.2
+  version: 2.1.4
 platform: ruby
 authors:
 - Jim Gay
@@ -46,7 +46,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 3.7.2
 specification_version: 4
 summary: Simple state machine
 test_files: []