circulator 2.1.5 → 2.1.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4c511772e424334259794bfff3d3507e5740fc98f0a130c66bf1d77a41862f6a
-  data.tar.gz: 7ee239ac23cbd6998a6d1689f8d6729983b42a6d6081e092465483ee19013107
+  metadata.gz: 63f6c8044ac3e21dffede73e1345d33d2e1e3f77350bcd6b332df8508d810f1f
+  data.tar.gz: 65ef2f903e7ec29993e1bbf7cf7b522c0d7bcba0cd424c75a7271ff0a89478db
 SHA512:
-  metadata.gz: 63e6165e93a276d89ac6c469c3e8b5db41e6b184cde3290a9ff1332992e7f27a06cf1cd8f8b93c32100986c27be3761d0cfbc9ef7c69414b0cd379f32813c018
-  data.tar.gz: 586cdd39db8b98b10465e84c02de948a44f39c556ae270ea6a68ea8f90ca8c0b61af37917419dfe599e39e882584101169f932671996edbeeb97d6e9debe806d
+  metadata.gz: c06f5b31e89fdd3832c8339b6884546b72b651395c2ca0a81cd37767f0a482dac2507ab45120bfe95fcaa950d6359080170859cb6ff1db61c485b165386df99d
+  data.tar.gz: 7a9f34b128d42a5c1ef9c45b806de26ac318bd822df6fbb6d35ffaa3df8384ac0dda2833057076cbb6715a30d98685a4eda03c73e6c2352a2d5682fa8a0c3260

data/CHANGELOG.md

@@ -5,10 +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.5] - 2025-11-15
+## [2.1.7] - 2026-01-06
 
 ### Added
 
-- 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)
+- Use an array of mulitple symbols with allow_if guard clauses. (96b66e6)
+
+### Changed
+
+- Documentation of lib/circulator.rb and explain extensions in README.md (7a04d58)

data/README.md

@@ -173,6 +173,14 @@ end
 
 This is equivalent to the proc-based approach but cleaner when you have a dedicated method for the condition.
 
+You can also use an array of symbols to represent multiple conditions:
+
+```ruby
+action :publish, to: :published, allow_if: [:ready_to_publish?, :reviewed_by_present?]
+```
+
+This is equivalent to the proc-based approach but cleaner when you have multiple conditions.
+
 **Hash-based guards** check the state of another attribute:
 
 You can make one state machine depend on another using hash-based `allow_if`:
@@ -285,10 +293,131 @@ class Payment
 end
 ```
 
+#### Extending Flows
+
+You can extend existing flows using `Circulator.extension`. This is useful for plugins, multi-tenant applications, or conditional feature enhancement. Extensions are registered globally and automatically applied when a class defines its flow.
+
+**Basic Extension Example:**
+
+```ruby
+class Document
+  extend Circulator
+
+  attr_accessor :status
+
+  flow :status do
+    state :draft do
+      action :submit, to: :review
+    end
+
+    state :review do
+      action :approve, to: :approved
+    end
+
+    state :approved
+  end
+end
+
+# Register extension - can be in a separate file or initializer
+Circulator.extension(:Document, :status) do
+  state :review do
+    action :reject, to: :rejected
+  end
+
+  state :rejected do
+    action :revise, to: :draft
+  end
+end
+
+# Extensions are automatically applied when class is loaded
+doc = Document.new
+doc.status = :review
+doc.status_reject  # => :rejected (from extension)
+doc.status_revise  # => :draft (from extension)
+```
+
+**How Extensions Work:**
+
+Extensions are registered globally using `Circulator.extension(class_name, attribute)` and are automatically applied when the class defines its flow. Multiple extensions can be registered for the same class/attribute and are applied in registration order. Extensions must be registered before the class definition (typically in initializers).
+
+By default, when an extension defines the same action from the same state as the base flow, the extension completely replaces the base definition (last-defined wins). To implement intelligent composition where extensions add their conditions/blocks additively, your application can configure a custom `flows_proc` that uses a Hash-like object with merge logic. Circulator remains dependency-free and supports any compatible Hash implementation.
+
+**Plugin-Style Extensions:**
+
+Extensions are perfect for gems that want to extend Circulator workflows without modifying the host application:
+
+```ruby
+# gem_name/lib/gem_name.rb
+Circulator.extension(:BlogPost, :status) do
+  state :draft do
+    action :generate_seo, to: :draft do
+      generate_meta_tags
+    end
+  end
+
+  state :published do
+    action :schedule_social, to: :published do
+      queue_social_sharing
+    end
+  end
+end
+
+# Host application doesn't need to know about the plugin's extensions
+class BlogPost
+  extend Circulator
+
+  flow :status do
+    state :draft do
+      action :publish, to: :published
+    end
+    state :published
+  end
+end
+
+# Plugin actions are automatically available
+post = BlogPost.new
+post.status = :draft
+post.status_generate_seo  # From plugin extension
+post.status_publish       # From base flow
+```
+
+**Conditional Extensions Based on Feature Flags:**
+
+```ruby
+# config/initializers/circulator_extensions.rb
+if ENV['ENABLE_APPROVAL_WORKFLOW']
+  Circulator.extension(:Document, :status) do
+    state :draft do
+      action :submit_for_approval, to: :approval
+    end
+
+    state :approval do
+      action :approve, to: :approved
+      action :reject, to: :draft
+    end
+
+    state :approved
+  end
+end
+
+# Base flow always available, additional workflow only when enabled
+class Document
+  extend Circulator
+
+  flow :status do
+    state :draft do
+      action :save, to: :draft
+    end
+  end
+end
+```
+
 ### Generating Diagrams
 
 You can generate diagrams for your Circulator models using the `circulator-diagram` executable. By default, it will generate a DOT file. You can also generate a PlantUML file by passing the `-f plantuml` option.
 
+#### Generate a diagram for a specific model:
+
 ```bash
 bundle exec circulator-diagram MODEL_NAME
 ```
@@ -297,6 +426,30 @@ bundle exec circulator-diagram MODEL_NAME
 bundle exec circulator-diagram MODEL_NAME -f plantuml
 ```
 
+#### Generate diagrams for all models with Circulator flows:
+
+Use the `--all` option to automatically find and generate diagrams for all classes that have Circulator flows defined:
+
+```bash
+bundle exec circulator-diagram --all
+```
+
+```bash
+bundle exec circulator-diagram --all -f plantuml
+```
+
+The `--all` option will:
+- Automatically discover all classes with Circulator flows (including classes that inherit from a parent that extends Circulator)
+- Eager load Rails application classes if running in a Rails environment
+- Generate diagrams for each class found
+- Use the same output directory and format options as single-model generation
+
+#### Other options:
+
+- `-d, --directory DIRECTORY` - Specify output directory (default: `docs`)
+- `-s, --separate` - Generate separate diagram files for each flow attribute
+- `-r, --require FILE` - Require a file before loading models (e.g., `config/environment`)
+
 ## Why Circulator?
 
 Circulator distinguishes itself from other Ruby state machine libraries through its simplicity and flexibility:

data/exe/circulator-diagram

@@ -8,17 +8,21 @@ require_relative "../lib/circulator/dot"
 require_relative "../lib/circulator/plantuml"
 
 # Parse command-line options
-options = {format: "dot", require: nil, directory: "docs", separate: false}
+options = {format: "dot", require: nil, directory: "docs", separate: false, all: false}
 parser = OptionParser.new do |opts|
-  opts.banner = "Usage: circulator-diagram MODEL_NAME [options]"
+  opts.banner = "Usage: circulator-diagram [MODEL_NAME | --all] [options]"
   opts.separator ""
   opts.separator "Generate diagram files for Circulator state machine flows"
   opts.separator ""
   opts.separator "Arguments:"
-  opts.separator "  MODEL_NAME    Name of the model class with Circulator flows"
+  opts.separator "  MODEL_NAME    Name of the model class with Circulator flows (required unless --all is used)"
   opts.separator ""
   opts.separator "Options:"
 
+  opts.on("-a", "--all", "Generate diagrams for all classes with Circulator in their ancestry") do
+    options[:all] = true
+  end
+
   opts.on("-f", "--format FORMAT", ["dot", "plantuml"], "Output format (dot, plantuml). Default: dot") do |format|
     options[:format] = format
   end
@@ -54,15 +58,15 @@ rescue OptionParser::InvalidOption => e
   exit 1
 end
 
-# Check for required model name argument
-if ARGV.empty?
-  warn "Error: MODEL_NAME is required"
+# Check for required model name argument or --all flag
+if ARGV.empty? && !options[:all]
+  warn "Error: Either MODEL_NAME or --all is required"
   warn ""
   warn parser
   exit 1
 end
 
-model_name = ARGV[0]
+model_name = ARGV[0] unless options[:all]
 
 # Load the application environment
 # Priority: -r option > config/environment.rb > nothing
@@ -79,22 +83,63 @@ elsif File.exist?("config/environment.rb")
   require File.expand_path("config/environment.rb")
 end
 
-# Try to constantize the model name
-begin
-  model_class = Object.const_get(model_name)
-rescue NameError
-  warn "Error: Model '#{model_name}' not found"
-  warn "Make sure the model is loaded in your environment"
-  exit 1
+# Find all classes with Circulator in their ancestry
+def find_circulator_classes
+  classes = []
+
+  # Try to force-load classes that might not be loaded yet
+  # This is especially important for Rails apps with lazy loading
+  if defined?(Rails) && Rails.application
+    begin
+      Rails.application.eager_load!
+    rescue => e
+      warn "Warning: Could not eager load Rails application: #{e.message}"
+    end
+  end
+
+  ObjectSpace.each_object(Class) do |klass|
+    # Skip anonymous classes and classes without names
+    next if klass.name.nil? || klass.name.empty?
+
+    # Check if the class responds to :flows (set up when Circulator is extended)
+    next unless klass.respond_to?(:flows)
+
+    begin
+      flows = klass.flows
+      next if flows.nil? || flows.empty?
+    rescue => e
+      # Skip classes where flows method raises an error
+      warn "Warning: Could not get flows for #{klass.name}: #{e.class} - #{e.message}"
+      next
+    end
+
+    classes << klass
+  rescue => e
+    # Skip any class that causes an error during inspection
+    if ENV["DEBUG"]
+      warn "Warning: Error inspecting class #{begin
+        klass.name
+      rescue
+        "unknown"
+      end}: #{e.class} - #{e.message}"
+    end
+    next
+  end
+
+  classes.sort_by(&:name)
 end
 
-# Generate diagram file(s)
-begin
-  generator = case options[:format]
-  when "plantuml"
-    Circulator::PlantUml.new(model_class)
-  else
-    Circulator::Dot.new(model_class)
+# Generate diagram for a single model class
+def generate_diagram_for_class(model_class, options)
+  begin
+    generator = case options[:format]
+    when "plantuml"
+      Circulator::PlantUml.new(model_class)
+    else
+      Circulator::Dot.new(model_class)
+    end
+  rescue => e
+    raise "Failed to initialize diagram generator for #{model_class.name}: #{e.class} - #{e.message}"
   end
 
   # Determine base output filename and extension
@@ -163,6 +208,59 @@ begin
       puts "  dot -Tpng #{output_file} -o #{File.join(options[:directory], base_name)}.png"
     end
   end
+end
+
+# Collect classes to generate diagrams for
+begin
+  if options[:all]
+    # Find all classes with Circulator in their ancestry
+    begin
+      classes_to_process = find_circulator_classes
+    rescue => e
+      warn "Error finding Circulator classes: #{e.class} - #{e.message}"
+      warn e.backtrace.first(10).join("\n")
+      exit 1
+    end
+
+    if classes_to_process.empty?
+      warn "No classes with Circulator flows found"
+      exit 1
+    end
+
+    puts "Found #{classes_to_process.size} class(es) with Circulator flows:"
+    classes_to_process.each do |klass|
+      puts "  - #{klass.name}"
+    end
+    puts ""
+  else
+    # Try to constantize the model name
+    begin
+      model_class = Object.const_get(model_name)
+    rescue NameError
+      warn "Error: Model '#{model_name}' not found"
+      warn "Make sure the model is loaded in your environment"
+      exit 1
+    end
+
+    classes_to_process = [model_class]
+  end
+
+  # Generate diagrams for all classes in the array
+  classes_to_process.each do |model_class|
+    if classes_to_process.size > 1
+      puts "Generating diagram for #{model_class.name}..."
+    end
+
+    begin
+      generate_diagram_for_class(model_class, options)
+    rescue => e
+      warn "Error generating diagram for #{model_class.name}: #{e.class} - #{e.message}"
+      warn e.backtrace.first(5).join("\n") if ENV["DEBUG"]
+      next
+    end
+
+    puts "" if classes_to_process.size > 1
+  end
 
   exit 0
 rescue ArgumentError => e

data/lib/circulator/flow.rb

@@ -98,8 +98,10 @@ module Circulator
         validate_symbol_allow_if(allow_if)
       in Hash
         validate_hash_allow_if(allow_if)
+      in Array
+        validate_array_allow_if(allow_if)
       else
-        raise ArgumentError, "allow_if must be a Proc, Hash, or Symbol, got: #{allow_if.class}"
+        raise ArgumentError, "allow_if must be a Proc, Hash, Symbol, or Array, got: #{allow_if.class}"
       end
     end
 
@@ -141,6 +143,25 @@ module Circulator
       end
     end
 
+    def validate_array_allow_if(allow_if_array)
+      # Array must not be empty
+      if allow_if_array.empty?
+        raise ArgumentError, "allow_if array must not be empty"
+      end
+
+      # First, validate all element types
+      allow_if_array.each do |element|
+        unless element.is_a?(Symbol) || element.is_a?(Proc)
+          raise ArgumentError, "allow_if array elements must be Symbols or Procs, got: #{element.class}"
+        end
+      end
+
+      # Then, validate that Symbol methods exist
+      allow_if_array.each do |element|
+        validate_symbol_allow_if(element) if element.is_a?(Symbol)
+      end
+    end
+
     def apply_extensions
       # Look up extensions for this class and attribute
       class_name = if @klass.is_a?(Class)

data/lib/circulator/version.rb

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

data/lib/circulator.rb

@@ -7,20 +7,64 @@ module Circulator
 
   @default_flow_proc = ::Hash.method(:new)
   class << self
+    # Returns the global registry of registered extensions
+    #
+    # The registry is a Hash where keys are "ClassName:attribute_name" strings
+    # and values are Arrays of extension blocks.
+    #
+    # Example:
+    #
+    #   Circulator.extensions["Document:status"]
+    #   # => [<Proc>, <Proc>]  # Array of extension blocks
     attr_reader :extensions
+
+    # The default Proc used to create transition_maps for flows
+    #
+    # By default, this returns Hash.method(:new), which creates regular Hashes.
+    # Can be overridden to use custom storage implementations (e.g., any Hash-like object
+    # with custom merge behavior) by setting @default_flow_proc before defining flows.
     attr_reader :default_flow_proc
 
     # Register an extension for a specific class and attribute
     #
+    # Extensions allow you to add additional states and transitions to existing flows
+    # without modifying the original class definition. This is useful for:
+    # - Plugin gems extending host application workflows
+    # - Multi-tenant applications with customer-specific flows
+    # - Conditional feature enhancement based on configuration
+    #
+    # Extensions are registered globally and automatically applied when the class
+    # defines its flow. Multiple extensions can be registered for the same class/attribute.
+    #
     # Example:
     #
     #   Circulator.extension(:Document, :status) do
     #     state :pending do
     #       action :send_to_legal, to: :legal_review
     #     end
+    #
+    #     state :legal_review do
+    #       action :approve, to: :approved
+    #     end
     #   end
     #
-    # Extensions are automatically applied when the class defines its flow
+    # Merging behavior (default):
+    # When an extension defines the same action from the same state as the base flow,
+    # the extension completely replaces the base definition (last-defined wins).
+    #
+    # Custom merging:
+    # To implement intelligent composition where extensions add conditions/blocks additively,
+    # pass a custom flows_proc parameter to your flow() definition that creates a Hash-like
+    # object with custom merge logic.
+    #
+    # Extension registration must happen before class definition (typically in initializers).
+    #
+    # Arguments:
+    # - class_name: Symbol or String - Name of class being extended
+    # - attribute_name: Symbol or String - Name of the flow attribute
+    # - block: Required block containing state and action definitions
+    #
+    # Raises ArgumentError if no block provided.
     def extension(class_name, attribute_name, &block)
       raise ArgumentError, "Block required for extension" unless block_given?
 
@@ -223,8 +267,18 @@ module Circulator
       end
 
       if transition[:allow_if]
+        # Handle array-based allow_if (array of symbols and/or procs)
+        if transition[:allow_if].is_a?(Array)
+          return unless transition[:allow_if].all? do |guard|
+            case guard
+            when Symbol
+              flow_target.send(guard, *args, **kwargs)
+            when Proc
+              flow_target.instance_exec(*args, **kwargs, &guard)
+            end
+          end
         # Handle hash-based allow_if (checking other attribute states)
-        if transition[:allow_if].is_a?(Hash)
+        elsif 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)
 
@@ -341,6 +395,45 @@ module Circulator
       available_flows(attribute, *args, **kwargs).include?(action)
     end
 
+    # Get the guard methods for a specific transition
+    #
+    # Returns an array of Symbol method names if the guard is an array of symbols,
+    # or nil if no guard or guard is not an array.
+    #
+    # Example:
+    #
+    #   class Order
+    #     extend Circulator
+    #     flow(:status) do
+    #       state :pending do
+    #         action :approve, to: :approved, allow_if: [:approved?, :in_budget?]
+    #       end
+    #     end
+    #   end
+    #
+    #   order = Order.new
+    #   order.guards_for(:status, :approve)
+    #   # => [:approved?, :in_budget?]
+    def guards_for(attribute, action)
+      model_key = Circulator.model_key(self)
+      flow = flows.dig(model_key, attribute)
+      return nil unless flow
+
+      current_value = send(attribute)
+      current_state = current_value.respond_to?(:to_sym) ? current_value.to_sym : current_value
+
+      transition = flow.transition_map.dig(action, current_state)
+      return nil unless transition
+
+      guard = transition[:allow_if]
+      return nil unless guard
+
+      # If guard is an array, return only the Symbol elements
+      if guard.is_a?(Array)
+        guard.select { |g| g.is_a?(Symbol) }
+      end
+    end
+
     private
 
     def flows
@@ -349,6 +442,16 @@ module Circulator
 
     def check_allow_if(allow_if, *args, **kwargs)
       case allow_if
+      when Array
+        # All guards in array must be true (AND logic)
+        allow_if.all? do |guard|
+          case guard
+          when Symbol
+            send(guard, *args, **kwargs)
+          when Proc
+            instance_exec(*args, **kwargs, &guard)
+          end
+        end
       when Hash
         attribute_name, valid_states = allow_if.first
         current_state = send(attribute_name)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: circulator
 version: !ruby/object:Gem::Version
-  version: 2.1.5
+  version: 2.1.7
 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.7.2
+rubygems_version: 4.0.3
 specification_version: 4
 summary: Simple state machine
 test_files: []