circulator 2.1.1 → 2.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 31b604ea699b2cbe133905f3078e81aa7860bc4e70e52cfd928611b92140b3f8
-  data.tar.gz: e264bd9c50f93fb1ab9f606a0d6b670ce4708304ccdf4a04a67a3a2e588b5bf5
+  metadata.gz: bdd2e4e17046d72b53d25ea469b8f037316abf74cb7a34fe010091ff4f8b5bfa
+  data.tar.gz: 879a93ab33bb08c07fb6239ce490c5d900272cbd3cd03a65c66516f95439499e
 SHA512:
-  metadata.gz: 80262bad01b9861f1f20459a67c80fbbd77c1f4cf4bc661d5b5918bd727582e8e099871cfd63b29a973fc5998a0c942a0f63aa2ced5894d41de91b5722517b19
-  data.tar.gz: fcbd512e14e020ee4ede8cb34b0432b46c38fbfee246c43a14906f0711302825e633376e8bb1b98c00eee55a24396c5e5814e1fd394dbc8f5a106737a615cb39
+  metadata.gz: 910cd9755d9b9c02996d9d38329082733d019019151c19bc839663893e3523a6c64be9149485317bc7a0979f10223d15c4e0bb34ae0a9942f30d1c473acf8378
+  data.tar.gz: a98cad092d4da49cf93c38db6462489730061c38439f9825e2d2378ef58def38d3db243784c570f50697704442d271d8ac3aa0b1eddd5147e7f4a65b2a346c8a

data/CHANGELOG.md

@@ -5,9 +5,12 @@ 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.1] - 2025-10-06
+## [2.1.3] - 2025-10-27
+
+### Fixed
+
+- Ignore nil states in predicate methods (73c74c2)
 
 ### Added
 
-- Visual organization for separate flows in generated diagrams
-- Ability to generate separate diagrams for each flow in a class.
+- Attribute predicate methods and documentation (8f9cc33)

data/README.md

@@ -6,8 +6,9 @@ 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
 - **Multiple State Machines**: Define multiple independent state machines per class
 - **Framework Agnostic**: Works with plain Ruby objects, no Rails or ActiveRecord required
@@ -71,6 +72,37 @@ 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.
+
 ### Advanced Features
 
 #### Conditional Transitions with Guards
@@ -93,6 +125,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
@@ -189,7 +258,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/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/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Circulator
-  VERSION = "2.1.1"
+  VERSION = "2.1.3"
 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/
@@ -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)
@@ -170,7 +196,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.1
+  version: 2.1.3
 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: []