circulator 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 34d38ad852dfc0dea3071103c368fa9d77224c7a390b7fc10c6a39fde2e2b507
+  data.tar.gz: c67068423ece22963cdf64391f0424251a8c23caebf08280a6bb977b1a18bd4b
+SHA512:
+  metadata.gz: dc4264165cdb3fdf72ec246dcabc02c0bacff9d20f24a167984e6521517550cc131fd0711f289892c8263fea6ac6c07dcc1d39c0ed77165dbf74d2a3d044f331
+  data.tar.gz: d85440b2e40cc2aa2ff1f7848f5b4dc63b94c2217ebdd7918488967489badb439edcb1c5f39c0b762634f1739ce38405ad19e841a7f4b84c2bb8671262418ec3

data/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+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).
+
+## [1.0.0] - 2025-09-11
+
+### 
+
+- Initial release.

data/README.md

@@ -0,0 +1,227 @@
+# Circulator
+
+A lightweight and flexible state machine implementation for Ruby that allows you to define and manage state transitions with an simple DSL. Circulator provides a simple yet powerful way to add state machine functionality to your Ruby classes without the complexity of larger frameworks.
+
+## Key Features
+
+- **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
+- **Conditional Transitions**: Support for guards and conditional logic
+- **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
+- **100% Test Coverage**: Thoroughly tested with comprehensive test suite
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'circulator'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install circulator
+```
+
+## Usage
+
+### Basic Example
+
+```ruby
+class Order
+  extend Circulator::Diverter
+
+  attr_accessor :status
+
+  circulator :status do
+    state :pending do
+      action :process, to: :processing
+      action :cancel, to: :cancelled
+    end
+
+    state :processing do
+      action :ship, to: :shipped
+      action :cancel, to: :cancelled
+    end
+
+    state :shipped do
+      action :deliver, to: :delivered
+    end
+
+    state :delivered
+    state :cancelled
+  end
+end
+
+order = Order.new
+order.status = :pending
+
+order.status_process  # => :processing
+order.status_ship     # => :shipped
+order.status_deliver  # => :delivered
+```
+
+### Advanced Features
+
+#### Conditional Transitions with Guards
+
+```ruby
+class Document
+  extend Circulator::Diverter
+
+  attr_accessor :state, :reviewed_by
+
+  circulator :state do
+    state :draft do
+      action :submit, to: :review
+
+      action :publish, to: :published, allow_if: -> { reviewed_by.present? } do
+        puts "Publishing document reviewed by #{reviewed_by}"
+      end
+    end
+  end
+end
+```
+
+#### Dynamic Destination States
+
+```ruby
+class Task
+  extend Circulator::Diverter
+
+  attr_accessor :priority, :urgency_level
+
+  circulator :priority do
+    state :normal do
+      # Destination determined at runtime
+      action :escalate, to: -> { urgency_level > 5 ? :critical : :high }
+    end
+  end
+end
+```
+
+#### Multiple State Machines
+
+```ruby
+class Server
+  extend Circulator::Diverter
+
+  attr_accessor :power_state, :network_state
+
+  # First state machine for power management
+  circulator :power_state do
+    state :off do
+      action :boot, to: :booting
+    end
+    state :booting do
+      action :ready, to: :on
+    end
+    state :on do
+      action :shutdown, to: :off
+    end
+  end
+
+  # Second state machine for network status
+  circulator :network_state do
+    state :disconnected do
+      action :connect, to: :connected
+    end
+    state :connected do
+      action :disconnect, to: :disconnected
+    end
+  end
+end
+```
+
+#### Transition Callbacks
+
+```ruby
+class Payment
+  extend Circulator::Diverter
+
+  attr_accessor :status, :processed_at
+
+  circulator :status do
+    state :pending do
+      action :process, to: :completed do
+        self.processed_at = Time.now
+        send_confirmation_email
+      end
+    end
+  end
+
+  private
+
+  def send_confirmation_email
+    # Send email logic here
+  end
+end
+```
+
+## Why Circulator?
+
+Circulator distinguishes itself from other Ruby state machine libraries through its simplicity and flexibility:
+
+### Advantages Over Other Libraries
+
+- **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`)
+- **Flexible Architecture**: Easy to extend and customize for specific needs
+
+### When to Use Circulator
+
+Choose Circulator when you need:
+- A simple, lightweight state machine without framework dependencies
+- Clear, predictable method naming conventions
+- Multiple independent state machines on the same object
+- Easy-to-understand code without DSL complexity
+- Full control over state transition logic
+
+## Related Projects
+
+If Circulator doesn't meet your needs, consider these alternatives:
+
+- **[AASM](https://github.com/aasm/aasm)** - Full-featured state machine with ActiveRecord integration and extensive callbacks
+- **[state_machines](https://github.com/state-machines/state_machines)** - Comprehensive state machine library with GraphViz visualization support
+- **[workflow](https://github.com/geekq/workflow)** - Workflow-focused state machine with emphasis on business processes
+- **[statesman](https://github.com/gocardless/statesman)** - Database-backed state machines with transition history
+- **[finite_machine](https://github.com/piotrmurach/finite_machine)** - Minimal finite state machine with a simple DSL
+
+Each library has its strengths:
+- Use **AASM** for Rails applications needing ActiveRecord integration
+- Use **state_machines** for complex state logic with visualization needs
+- Use **workflow** for business process modeling
+- Use **statesman** when audit trails and transition history are critical
+- Use **finite_machine** for thread-safe state machines
+- Use **Circulator** for lightweight, flexible state management without dependencies
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run bundle exec rake install.
+
+This project is managed with [Reissue](https://github.com/SOFware/reissue).
+
+To release a new version, make your changes and be sure to update the CHANGELOG.md.
+
+To release a new version:
+
+    bundle exec rake build:checksum
+    bundle exec rake release
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/SOFware/circulator.

data/Rakefile

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+require "standard/rake"
+
+task default: %i[test standard]
+
+require "reissue/gem"
+
+Reissue::Task.create :reissue do |task|
+  task.version_file = "lib/circulator/version.rb"
+  task.changelog_file = "CHANGELOG.md"
+  task.version_limit = 1
+end

data/lib/circulator/diverter.rb

@@ -0,0 +1,242 @@
+# frozen_string_literal: true
+
+module Circulator
+  module Diverter
+    # Declare a flow for an attribute.
+    #
+    # Specify the attribute to be used for states and actions.
+    #
+    # Example:
+    #
+    #   flow(:status) do
+    #     state :pending do
+    #       action :approve, to: :approved
+    #     end
+    #   end
+    #
+    # The above declares a flow for the `status` attribute. When in the `pending`
+    # state, the `approve` action will transition the `status` to `approved`.
+    #
+    # This creates a `status_approve` method which will change the state in memory.
+    #
+    # You will also have a instance method `flow` which will allow you to specify
+    # the action to take on the attribute.
+    #
+    # Example:
+    #
+    #   test_object.status_approve
+    #   # OR
+    #   test_object.flow(:approve, :status)
+    #
+    # You can also provide a block to receive arguments
+    #
+    # Example:
+    #
+    #   flow(:status) do
+    #     state :pending do
+    #       action :approve, to: :approved do |*args, **kwargs|
+    #         @args_received = {args: args, kwargs: kwargs}
+    #       end
+    #       action_allowed(:approve) { true } # Optional. Check some value on self
+    #     end
+    #   end
+    #
+    # The block will be evalutaed on the instance of the class declaring the flow.
+    # So `self` inside that action block will be the instance of the class.
+    #
+    # Example:
+    #
+    #   test_object.status_approve("arg1", "arg2", key: "value")
+    #   # @args_received will be {args: ["arg1", "arg2"], kwargs: {key: "value"}}
+    #
+    # If the action is not allowed, the transition will not be executed.
+    #
+    # Example:
+    #
+    #  flow(:status) do
+    #    state :pending do
+    #      action :approve, to: :approved do
+    #        @args_received = {args: args, kwargs: kwargs}
+    #      end
+    #      action_allowed(:approve) { false }
+    #    end
+    #  end
+    #
+    #  test_object.status_approve
+    #  # Will not transition because the action is not allowed
+    #
+    # You may also specify the `allow_if` option to check a condition before
+    # the action is allowed. The callable will be evaluated on the instance of
+    # the class declaring the flow. So `self` inside that block will be the
+    # instance of the class.
+    #
+    # Example:
+    #
+    #  flow(:status) do
+    #    state :pending do
+    #      action :approve, to: :approved, allow_if: -> { true }
+    #    end
+    #  end
+    #
+    #  test_object.status_approve
+    #  # Will transition to :approved if the condition is true
+    #
+    # If you declare states separately, for example in an enum, you can use the
+    # `action` method to declare the action on the attribute.
+    #
+    # Example:
+    #
+    #  enum :status, {pending: 0, approved: 1, rejected: 2}
+    #  flow(:status) do
+    #    action :approve, to: :approved, from: :pending
+    #    action :reject, to: :rejected, from: :approved do |rejected_at|
+    #      self.rejected_at = rejected_at
+    #    end
+    #  end
+    #
+    #  test_object.status_approve
+    #  # Will transition to :approved
+    #  test_object.status_reject
+    #  # Will transition to :rejected and set the rejected_at attribute
+    #
+    # By default, if there is no transition for the current state, the flow will
+    # raise an error. You can specify a no_action block to handle this case.
+    #
+    # Example:
+    #
+    #  flow(:status) do
+    #    no_action { |attribute_name, action| raise "Nope!" }
+    #  end
+    #
+    #  test_object.status_approve
+    #  # Will raise an error
+    #
+    # You can also provide a custom action for other behavior for a set of states and
+    # use the `to` option as a callable to set the attribute.
+    #
+    # Example:
+    #
+    #  flow(:status) do
+    #    action :unknown, to: -> { status }, from: [:enforcing, :monitoring, :ignoring] do |signal|
+    #      raise UnhandledSignalError, signal
+    #    end
+    #  end
+    #
+    #  test_object.flow(:unknown, :status, "signal")
+    #  # Will raise an UnhandledSignalError
+    #
+    def flow(attribute_name, model: to_s, &block)
+      @flows ||= {}
+      model_key = Circulator::Diverter.model_key(model)
+      @flows[model_key] ||= {}
+      @flows[model_key][attribute_name] = Circulator::Flow.new(model, attribute_name, &block)
+
+      flow_module = ancestors.find { |ancestor|
+        ancestor.name.to_s =~ /FlowMethods/
+      } || Module.new.tap do |mod|
+        include mod
+
+        const_set(:FlowMethods, mod)
+      end
+
+      object = if model == to_s
+        nil
+      else
+        Circulator::Diverter.methodize_name(model)
+      end
+
+      @flows.dig(model_key, attribute_name).transition_map.each do |action, transitions|
+        define_flow_method(attribute_name:, action:, transitions:, object:, owner: flow_module)
+      end
+    end
+    alias_method :circulator, :flow
+
+    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)
+
+      owner.define_method(object_attribute_method) do |*args, flow_target: self, **kwargs, &block|
+        current_value = flow_target.send(attribute_name)
+
+        transition = if current_value.respond_to?(:to_sym)
+          transitions[current_value.to_sym]
+        else
+          transitions[current_value]
+        end
+
+        unless transition
+          flow_target.instance_exec(attribute_name, action, &flows.dig(Circulator::Diverter.model_key(flow_target), attribute_name).no_action)
+          return
+        end
+
+        if transition[:allow_if]
+          return unless flow_target.instance_exec(*args, **kwargs, &transition[:allow_if])
+        end
+
+        if transition[:block]
+          flow_target.instance_exec(*args, **kwargs, &transition[:block])
+        end
+
+        if transition[:to].respond_to?(:call)
+          flow_target.send("#{attribute_name}=", flow_target.instance_exec(*args, **kwargs, &transition[:to]))
+        else
+          flow_target.send("#{attribute_name}=", transition[:to])
+        end.tap do
+          if block
+            flow_target.instance_exec(*args, **kwargs, &block)
+          end
+        end
+      end
+    end
+
+    module_function def model_key(object)
+      if object.is_a?(String)
+        if object.start_with?("#<Class:")
+          "anonymous_#{object.split("0x")[1]}".sub(">", "")
+        else
+          object
+        end
+      else
+        model_key(object.class.name || object.class.to_s)
+      end
+    end
+
+    module_function def methodize_name(name)
+      name.split("::").map { |part| part.gsub(/([a-z])([A-Z])/, '\1_\2') }.join("_").downcase
+    end
+
+    def self.extended(base)
+      base.include(InstanceMethods)
+      base.singleton_class.attr_reader :flows
+    end
+
+    module InstanceMethods
+      # Use this method to call an action on the attribute.
+      #
+      # Example:
+      #
+      #   test_object.flow(:approve, :status)
+      #   test_object.flow(:approve, :status, "arg1", "arg2", key: "value")
+      def flow(action, attribute, *args, flow_target: self, **kwargs, &block)
+        target_name = if flow_target != self
+          Circulator::Diverter.methodize_name(Circulator::Diverter.model_key(flow_target))
+        end
+        external_attribute_name = [target_name, attribute].compact.join("_")
+        method_name = "#{external_attribute_name}_#{action}"
+        if respond_to?(method_name)
+          send(method_name, *args, flow_target:, **kwargs, &block)
+        elsif flow_target.respond_to?(method_name)
+          flow_target.send(method_name, *args, **kwargs, &block)
+        else
+          raise "Invalid action for the current state of #{attribute} (#{flow_target.send(attribute).inspect}): #{action}"
+        end
+      end
+
+      private
+
+      def flows
+        self.class.flows
+      end
+    end
+  end
+end

data/lib/circulator/flow.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require_relative "diverter"
+
+module Circulator
+  class Flow
+    def initialize(klass, attribute_name, states = Set.new, &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)
+    end
+    attr_reader :transition_map
+
+    def state(name, &block)
+      name = name.to_sym if name.respond_to?(:to_sym)
+      @states.add(name)
+      @current_state = name
+      instance_eval(&block) if block
+      remove_instance_variable(:@current_state)
+    end
+
+    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__
+
+      @transition_map[name] ||= {}
+      selected_state = (from == :__not_specified__) ? @current_state : from
+
+      # Handle nil case specially - convert to [nil] instead of []
+      states_to_process = if selected_state.nil?
+        [nil]
+      else
+        Array(selected_state)
+      end
+
+      states_to_process.each do |from_state|
+        from_state = from_state.to_sym if from_state.respond_to?(:to_sym)
+        @states.add(from_state)
+        @transition_map[name][from_state] = {to:, block:}
+        @transition_map[name][from_state][:allow_if] = allow_if if allow_if
+      end
+    end
+
+    def action_allowed(name, from: :__not_specified__, &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__
+
+      selected_state = (from == :__not_specified__) ? @current_state : from
+
+      # Handle nil case specially - convert to [nil] instead of []
+      states_to_process = if selected_state.nil?
+        [nil]
+      else
+        Array(selected_state)
+      end
+
+      states_to_process.each do |from_state|
+        from_state = from_state.to_sym if from_state.respond_to?(:to_sym)
+        @states.add(from_state)
+        @transition_map[name][from_state][:allow_if] = block
+      end
+    end
+
+    def no_action(&block)
+      if block_given?
+        @no_action = block
+      else
+        @no_action
+      end
+    end
+  end
+end

data/lib/circulator/version.rb

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

data/lib/circulator.rb

@@ -0,0 +1,3 @@
+require "circulator/version"
+require "circulator/diverter"
+require "circulator/flow"

metadata

@@ -0,0 +1,48 @@
+--- !ruby/object:Gem::Specification
+name: circulator
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Jim Gay
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Simple declarative state machine
+email:
+- jim@saturnflyer.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- README.md
+- Rakefile
+- lib/circulator.rb
+- lib/circulator/diverter.rb
+- lib/circulator/flow.rb
+- lib/circulator/version.rb
+homepage: https://github.com/SOFware/circulator
+licenses: []
+metadata:
+  homepage_uri: https://github.com/SOFware/circulator
+  source_code_uri: https://github.com/SOFware/circulator
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.7
+specification_version: 4
+summary: Simple state machine
+test_files: []