stateful.rb 2.1.0 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e7967ca169b2665febfdca466537e2cbd087eda2d2033289ddb485e5b6311fb8
-  data.tar.gz: a9d2c650234ba4657338b61129823f6fbaccad9159827d65ba67e4ccf10a7c98
+  metadata.gz: 19870edf42d6c87988172b8041d30496fd4f06c2c47ecb6cfd1d2903ba47f3e5
+  data.tar.gz: 05f29ff4ddeb5ffe4317b9bc94bf6ee1089fd9c27e88ebb1876512ff05fd3ff6
 SHA512:
-  metadata.gz: c19933b56be3391784e694fecedfb486c9b9f3be79a53d07ac5a0adb7c481aa8e68a5a0204ad48ea5869bf5385de38d0022767f14dbb5d4d247cdc00233e1379
-  data.tar.gz: d8cebec2d02b438a6756cdf297a11ccb1abe5927bf487b283e978df90a0a79eaca6598cccca4f15a55bb654af9b20a8866bb130be7ed887f174cc81ba09ec257
+  metadata.gz: 4126dfa52b171f819e7d9144e926c5ffcf8b80a9ad4ee0d2fbae09f61571a1955939a12ad9864d5c4639ab49fecbabc7bed4113a7e13adc1640ac54adf588104
+  data.tar.gz: cf3ec7be8218914f4f84d1f6a950e2ed42d46bfe5b70c6492d654ee884a2914add13da4cfb630446fd65a7088a2fe61e7cbb2951c470fd4e1bd0c120eda6675a

data/CHANGELOG.md

@@ -0,0 +1,137 @@
+# stateful/CHANGELOG.md
+
+## 2.2.0 (20260418): Add Sequel support.
+-----------------------------------------------------------------------------------------------------------------------
+
+### +
+1. lib/Stateful/Sequel.rb: Sequel adapter module, mirroring Stateful::ActiveRecord.
+2. lib/Stateful/Sequel/ClassMethods.rb: Sequel-specific class methods using self[:column] / self[:column]= for persistence.
+3. test/Sequel/test\_helper.rb: Sequel test helper using in-memory SQLite.
+4. test/Sequel.rb: Sequel test runner.
+5. test/Sequel/WithPersistenceNonSpecificExtend.rb
+6. test/Sequel/WithPersistenceNonSpecificExtendAndStatefulBlock.rb
+7. test/Sequel/WithPersistenceSpecificExtend.rb
+8. test/Sequel/WithPersistenceSpecificExtendAndStatefulBlock.rb
+9. test/Sequel/WithInitialStateBlock.rb
+10. test/Sequel/WithColumnName.rb
+11. test/Sequel/WithMultipleFinalStates.rb
+12. test/Sequel/WithMultipleStateMachines.rb
+13. test/Sequel/WithMultipleStateMachinesAndStatefulBlock.rb
+14. test/Sequel/WithExplicitDeterministicEventOrdering.rb
+15. test/Sequel/WithExplicitNonDeterministicEventOrdering.rb
+16. test/Sequel/WithExplicitGlobalNonDeterministicEventOrdering.rb
+17. test/Sequel/WithExplicitGlobalNonDeterministicEventOrderingAndInitialStateBlock.rb
+
+### ~
+1. lib/Stateful.rb: Auto-detect Sequel::Model in Stateful.extended, between ActiveRecord and Poro.
+2. test/Stateful.rb: + Sequel specs
+3. stateful.rb.gemspec: + sequel dev dependency; update description to include Sequel.
+4. lib/Stateful/VERSION.rb: /2.1.0/2.2.0/
+
+
+## 2.1.0 (20260412): Add mRuby support.
+-----------------------------------------------------------------------------------------------------------------------
+
+### +
+1. mrbgem.rake: mrbgem specification with spec.rbfiles pointing at lib/ directly.
+2. mruby/stub\_require\_relative.rb: Stub to silence require_relative calls at mRuby build time.
+3. mruby/smoke_test.rb: Smoke test for mRuby compatibility.
+4. TODO (See notes.txt.)
+
+### -
+1. CHANGELOG.txt as it was left empty after creating CHANGELOG.md.
+2. notes.txt (Now TODO.)
+
+### ~
+1. lib/Stateful.rb: + Object.const_defined?(:ActiveRecord) for mRuby compatibility. In mRuby defined?() raises NameError instead of returning nil as with CRuby.
+2. lib/Stateful/VERSION.rb: /2.0.0/2.1.0/
+
+
+## 2.0.0 (20260216): Allow multiple state machines per class.
+-----------------------------------------------------------------------------------------------------------------------
+
+### +
+1. Stateful::ClassMethods#state_machines: For indexing named `StateMachine` instances.
+2. Stateful::ClassMethods#state_machine
+3. Poro::ClassMethods#define_named_machine_methods
+4. ActiveRecord::ClassMethods#define_named_machine_methods
+5. StateMachine accepts parameter for `global_non_deterministic_event_ordering
+6. ~/test/ActiveRecord/test_helper.rb
+
+### -
+1. StateMachine#stateful
+
+### ~
+1. Stateful::ClassMethods#stateful: Use class_eval instead of delegating to StateMachine#stateful, which is now removed.
+2. /Stateful::States/Stateful::StateMachine/
+3. /stateful_states/stateful_state_machine/
+4. Test infrastructure migrated from PostgreSQL to SQLite (in-memory)
+5. stateful.rb.gemspec: /pg/sqlite3/
+6. Stateful::StateMachine#final_states: final_state?, final_states? weren't being defined.
+7. lib/Stateful/VERSION.rb: /1.0.2/2.1.0/
+
+
+## 1.0.2 (20260216): Fix non-deterministic event ordering.
+-----------------------------------------------------------------------------------------------------------------------
+
+### ~
+1. Stateful::State#non_deterministic_event_ordering?: Fixed logic bug where (@options[:deterministic] && !@options[:deterministic])  always evaluated to false.
+2. Stateful::States#global_non_deterministic_event_ordering?: Same fix as above.
+3. Stateful::State: /shuffle/shuffle!/non-deterministic ordering actually mutates the transitions array.
+4. Stateful::State: Removed require_relative for lib/Array/shuffle.rb.
+5. test/ActiveRecord/WithPersistenceSpecificExtend.rb: Fixed delete_all guard to check 'active_record_machine2s' instead of 'active_record_machine1s'.
+6. test/ActiveRecord/WithMultipleFinalStates.rb: Fixed comment header (was Poro/WithMultipleFinalStates.rb).
+7. test/Poro/WithVariableName.rb: Fixed comment header (was ActiveRecord/WithVariableName.rb).
+8. test/Poro/WithExplicitNonDeterministicEventOrdering.rb: Changed transition order assertions to use must_include instead of must_equal.
+9. test/ActiveRecord/WithExplicitNonDeterministicEventOrdering.rb: Same as above.
+10. test/ActiveRecord/WithExplicitGlobalNonDeterministicEventOrdering.rb: Same as above.
+11. test/ActiveRecord/WithExplicitGlobalNonDeterministicEventOrderingAndInitialStateBlock.rb: Same as above.
+12. lib/Stateful/VERSION.rb: /1.0.1/1.0.2/
+
+### -
+1. Array#shuffle: Use stdlib.
+
+
+## 1.0.1 (20260216): Fix date and version.
+-----------------------------------------------------------------------------------------------------------------------
+
+### ~
+1. stateful.rb.gemspec: Insert the correct date.
+2. lib/Stateful/VERSION.rb: /1.0.0/1.0.1/
+
+
+## 1.0.0 (20260216): Version number bump to 1.0.
+-----------------------------------------------------------------------------------------------------------------------
+
+### ~
+1. lib/Stateful/VERSION.rb: /0.14.12/1.0.0/
+
+
+## 0.14.12 (20260216): Change file mode on lib/Array/shuffle.rb.
+-----------------------------------------------------------------------------------------------------------------------
+
+### ~
+1. lib/Array/shuffle.rb: File mode change to read-only from being executable.
+2. lib/Stateful/VERSION.rb: /0.14.11/0.14.12/
+
+
+## 0.14.11 (20200419): Fix copypasta error in README.md.
+-----------------------------------------------------------------------------------------------------------------------
+
+### ~
+1. README.md: Fixed copypasta error in Installation section (was 'git.rb', now 'stateful.rb')
+2. lib/Stateful/VERSION.rb: /0.14.10/0.14.11/
+
+
+## 0.14.10 (20150207, 20200331): Allow Poro::ClassMethods to handle its own initialisation when extended.
+-----------------------------------------------------------------------------------------------------------------------
+
+### +
+1. I finally implemented a change which I'd had sitting in a file never committed named shouldgetthisworking.rb since 2015-02-07 which entails moving the instance method generation methods from each of the application-specific files (lib/Poro.rb and lib/ActiveRecord.rb) to the application-specific class methods files (lib/Poro/ClassMethods.rb and lib/ActiveRecord/ClassMethods.rb).
+2. README.md
+3. CHANGES.txt
+
+### ~
+1. .gitignore: + *.gem
+2. lib/Stateful/VERSION.rb: /0.14.9/0.14.10/
+3. stateful.rb.gemspec to reflect the updated version

data/Gemfile

@@ -0,0 +1,2 @@
+source 'https://www.rubygems.org'
+gemspec

data/README.md

@@ -0,0 +1,309 @@
+# Stateful
+
+## Description
+
+A Ruby state machine which allows you to easily add state to Poro and ActiveRecord objects. Works with both CRuby and mRuby.
+
+## Installation
+
+### CRuby
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'stateful.rb'
+```
+
+And then execute:
+
+```shell
+$ bundle install
+```
+
+Or install it yourself as:
+
+```shell
+$ gem install stateful.rb
+```
+
+### mRuby
+
+Add this to your `build_config.rb`:
+
+```ruby
+conf.gem github: 'thoran/Stateful'
+```
+
+## Usage
+
+### 1. Poro with persistence-specific extend and a stateful block declaration
+
+```ruby
+class PoroMachine
+  extend Stateful::Poro
+
+  stateful do
+    initial_state :initial_state
+
+    state :initial_state do
+      on :an_event => :next_state
+      on :another_event => :final_state
+    end
+
+    state :next_state do
+      on :yet_another_event => :final_state
+    end
+
+    final_state :final_state
+  end
+end
+
+poro_machine = PoroMachine.new
+poro_machine.initial_state.name
+# => :initial_state
+poro_machine.final_state.name
+# => :final_state
+```
+
+### 2. Poro with persistence non-specific extend, without a stateful block declaration, an initial_state block, and multiple final states
+
+```ruby
+class PoroMachine
+  extend Stateful
+
+  initial_state :initial_state do
+    on :an_event => :next_state
+    on :another_event => :final_state0
+  end
+
+  state :next_state do
+    on :yet_another_event => :final_state1
+  end
+
+  final_state :final_state0, :final_state1
+end
+
+poro_machine = PoroMachine.new
+poro_machine.current_state.name
+# => :initial_state
+poro_machine.an_event
+poro_machine.current_state.name
+# => :next_state
+```
+
+### 3. ActiveRecord with persistence-specific extend and a stateful block declaration
+
+```ruby
+class ActiveRecordMachine < ActiveRecord::Base
+  extend Stateful::ActiveRecord
+
+  stateful do
+    initial_state :initial_state
+
+    state :initial_state do
+      on :an_event => :next_state
+      on :another_event => :final_state
+    end
+
+    state :next_state do
+      on :yet_another_event => :final_state
+    end
+
+    final_state :final_state
+  end
+end
+
+active_record_machine = ActiveRecordMachine.new
+active_record_machine.initial_state?
+# => true
+active_record_machine.an_event
+active_record_machine.next_state?
+# => true
+```
+
+### 4. ActiveRecord with persistence non-specific extend, without a stateful block declaration, an initial_state block, and multiple final states
+
+```ruby
+class ActiveRecordMachine < ActiveRecord::Base
+  extend Stateful
+
+  initial_state :initial_state do
+    on :an_event => :next_state
+    on :another_event => :final_state0
+  end
+
+  state :next_state do
+    on :yet_another_event => :final_state0
+    on :and_yet_another_event => :final_state1
+  end
+
+  final_state :final_state0, :final_state1
+end
+
+active_record_machine = ActiveRecordMachine.new
+active_record_machine.an_event
+active_record_machine.final_state?
+# => false
+active_record_machine.yet_another_event
+active_record_machine.final_state?
+# => true
+```
+
+### 5. Custom variable/column name and non-deterministic event ordering
+
+It's also possible to define a state machine (either Poro or ActiveRecord) which has a custom variable (Poro) or column (ActiveRecord) name, which fires off the events in a random or non-deterministic order, and which has no final state.
+
+```ruby
+class ActiveRecordMachine < ActiveRecord::Base
+
+  @stateful_column_name = 'status' # This needs to be set before the class is extended. The default is 'current_state'.
+
+  extend Stateful
+
+  initial_state :initial_state, non_deterministic: true do
+    on :an_event => :another_state
+    on :another_event => :yet_another_state
+  end
+
+  state :another_state do
+    on :another_event => :yet_another_state
+  end
+
+  state :yet_another_state do
+    on :yet_another_event => :another_state
+  end
+end
+
+active_record_machine = ActiveRecordMachine.new
+# Supposing that both :an_event or :another_event messages are able to fire, then if the order of the evaluation of the transitions is non-deterministic, then the state change is also.  Non-deterministic event ordering really only makes sense in the context of the sibling library thoran/Eventful, which will evaluate the transitions automatically and will do so in the order as presented by Stateful.
+active_record_machine.another_event # With non-deterministic event firing it could check for :another_event before checking :an_event.
+active_record_machine.current_state.name
+# => :yet_another_state
+active_record_machine.an_event
+active_record_machine.current_state.name
+# => :yet_another_state
+active_record_machine.final_state?
+# => false
+active_record_machine.yet_another_event
+active_record_machine.final_state?
+# => false
+```
+
+### 6. Multiple state machines per class
+
+A single class can have multiple independent (orthogonal) state machines. Each machine gets its own namespaced methods, while domain predicates and event methods remain unnamespaced.
+
+```ruby
+class Order
+  extend Stateful
+
+  state_machine :fulfilment do
+    initial_state :pending do
+      on :items_collected => :ready
+    end
+
+    state :ready do
+      on :dispatch => :dispatched
+    end
+
+    final_state :dispatched
+  end
+
+  state_machine :payment do
+    initial_state :unpaid do
+      on :pay => :paid
+    end
+
+    state :paid do
+      on :refund => :refunded
+    end
+
+    final_state :refunded
+  end
+end
+
+order = Order.new
+
+order.fulfilment_state.name # state accessors are namespaced.
+# => :pending
+order.payment_state.name
+# => :unpaid
+
+order.fulfilment_initial_state? # General/overlapping predicates are namespaced.
+# => true
+order.payment_final_state?
+# => false
+
+order.fulfilment_transitions.first.event_name # Transitions are namespaced.
+# => :items_collected
+
+order.pending? # Domain predicates are not namespaced.
+# => true
+order.unpaid?
+# => true
+
+order.pay # Event methods are not namespaced.
+order.paid?
+# => true
+
+# State machines are orthogonal
+order.fulfilment_initial_state?
+# => true
+```
+
+Multiple state machines can also be declared inside a stateful block:
+
+```ruby
+class Order
+  extend Stateful
+
+  stateful do
+    state_machine :fulfilment do
+      initial_state :pending do
+        on :items_collected => :ready
+      end
+
+      state :ready do
+        on :dispatch => :dispatched
+      end
+
+      final_state :dispatched
+    end
+
+    state_machine :payment do
+      initial_state :unpaid do
+        on :pay => :paid
+      end
+
+      state :paid do
+        on :refund => :refunded
+      end
+
+      final_state :refunded
+    end
+  end
+end
+```
+
+For ActiveRecord, each machine uses a column named `<machine_name>_state`:
+
+```ruby
+class CreateOrders < ActiveRecord::Migration[6.0]
+  def change
+    create_table :orders do |t|
+      t.string :fulfilment_state
+      t.string :payment_state
+    end
+  end
+end
+```
+
+For Poro, each machine uses an instance variable named `@<machine_name>_state`.
+
+## Contributing
+
+1. Fork it: https://github.com/thoran/Stateful/fork
+2. Create your feature branch: `git checkout -b my-new-feature`
+3. Commit your changes: `git commit -am 'Add some feature'`
+4. Push to the branch: `git push origin my-new-feature`
+5. Create a new pull request

data/lib/Stateful/Sequel/ClassMethods.rb

@@ -0,0 +1,117 @@
+# Stateful/Sequel/ClassMethods.rb
+# Stateful::Sequel::ClassMethods
+
+module Stateful
+  module Sequel
+    module ClassMethods
+      class << self
+        def extended(klass)
+          klass.define_stateful_column_name_setter_method
+          klass.define_stateful_column_name_getter_method
+          klass.define_next_state_method
+          klass.define_transitions_method
+          klass.define_initial_stateQ_method
+          klass.define_final_stateQ_method
+        end
+      end # class << self
+
+      def define_named_machine_methods(machine_name)
+        define_stateful_column_name_setter_method(machine_name: machine_name)
+        define_stateful_column_name_getter_method(machine_name: machine_name)
+        define_next_state_method(machine_name: machine_name)
+        define_transitions_method(machine_name: machine_name)
+        define_initial_stateQ_method(machine_name: machine_name)
+        define_final_stateQ_method(machine_name: machine_name)
+      end
+
+      def stateful_column_name=(stateful_column_name)
+        @stateful_column_name = stateful_column_name
+      end
+
+      def stateful_column_name
+        @stateful_column_name
+      end
+
+      def column_name_for_machine(machine_name = nil)
+        if machine_name
+          "#{machine_name}_state"
+        else
+          instance_variable_get(:@stateful_column_name)
+        end
+      end
+
+      def define_event_method(transition, machine_name: nil)
+        stateful_column_name = column_name_for_machine(machine_name)
+        define_method(transition.event_name) do
+          next_state_name = self.send(stateful_column_name).next_state_name(transition.event_name)
+          next_state = self.class.stateful_state_machine(machine_name).find(next_state_name)
+          self.send("#{stateful_column_name}=", next_state)
+        end
+      end
+
+      def define_status_predicate_method(state_name, machine_name: nil)
+        stateful_column_name = column_name_for_machine(machine_name)
+        define_method("#{state_name}?") do
+          self.send(stateful_column_name).name == state_name
+        end
+      end
+
+      def define_stateful_column_name_setter_method(machine_name: nil)
+        stateful_column_name = column_name_for_machine(machine_name)
+        define_method("#{stateful_column_name}=") do |state|
+          instance_variable_set("@#{stateful_column_name}", self.class.stateful_state_machine(machine_name).find(state))
+          self[stateful_column_name.to_sym] = instance_variable_get("@#{stateful_column_name}").name.to_s
+          self.save
+          instance_variable_get("@#{stateful_column_name}")
+        end
+      end
+
+      def define_stateful_column_name_getter_method(machine_name: nil)
+        stateful_column_name = column_name_for_machine(machine_name)
+        define_method(stateful_column_name) do
+          instance_variable_set("@#{stateful_column_name}", self.class.stateful_state_machine(machine_name).find(self[stateful_column_name.to_sym]))
+          if state = instance_variable_get("@#{stateful_column_name}")
+            state
+          else
+            initial_state = self.class.stateful_state_machine(machine_name).initial_state
+            self.send("#{stateful_column_name}=", initial_state.name)
+            initial_state
+          end
+        end
+      end
+
+      def define_next_state_method(machine_name: nil)
+        stateful_column_name = column_name_for_machine(machine_name)
+        method_name = machine_name ? "#{machine_name}_next_state" : :next_state
+        define_method(method_name) do |event_name|
+          next_state_name = self.send(stateful_column_name).next_state_name(event_name)
+          self.class.stateful_state_machine(machine_name).find(next_state_name)
+        end
+      end
+
+      def define_transitions_method(machine_name: nil)
+        stateful_column_name = column_name_for_machine(machine_name)
+        method_name = machine_name ? "#{machine_name}_transitions" : :transitions
+        define_method(method_name) do
+          self.send(stateful_column_name).transitions
+        end
+      end
+
+      def define_initial_stateQ_method(machine_name: nil)
+        stateful_column_name = column_name_for_machine(machine_name)
+        method_name = machine_name ? "#{machine_name}_initial_state?" : :initial_state?
+        define_method(method_name) do
+          self.send(stateful_column_name) == self.class.stateful_state_machine(machine_name).initial_state
+        end
+      end
+
+      def define_final_stateQ_method(machine_name: nil)
+        stateful_column_name = column_name_for_machine(machine_name)
+        method_name = machine_name ? "#{machine_name}_final_state?" : :final_state?
+        define_method(method_name) do
+          self.class.stateful_state_machine(machine_name).final_states.include?(self.send(stateful_column_name))
+        end
+      end
+    end
+  end
+end

data/lib/Stateful/Sequel.rb

@@ -0,0 +1,30 @@
+# Stateful/Sequel.rb
+# Stateful::Sequel
+
+require_relative 'ClassMethods'
+require_relative 'InstanceMethods'
+require_relative File.join('Sequel', 'ClassMethods')
+
+module Stateful
+  module Sequel
+
+    class << self
+
+      def set_column_name(klass)
+        unless klass.instance_variable_get(:@stateful_column_name)
+          klass.instance_variable_set(:@stateful_column_name, 'current_state')
+        end
+      end
+
+      def extended(klass)
+        klass.extend(Stateful::ClassMethods)
+        klass.send(:include, Stateful::InstanceMethods)
+        set_column_name(klass)
+        klass.extend(Stateful::Sequel::ClassMethods)
+      end
+      alias_method :included, :extended
+
+    end # class << self
+
+  end
+end

data/lib/Stateful/VERSION.rb

@@ -1,3 +1,3 @@
 module Stateful
-  VERSION = '2.1.0'
+  VERSION = '2.2.0'
 end

data/lib/Stateful.rb

@@ -9,6 +9,9 @@ module Stateful
       if Object.const_defined?(:ActiveRecord) && defined?(::ActiveRecord::Base) && klass < ::ActiveRecord::Base
         require_relative File.join('Stateful', 'ActiveRecord')
         klass.extend(Stateful::ActiveRecord)
+      elsif Object.const_defined?(:Sequel) && defined?(::Sequel::Model) && klass < ::Sequel::Model
+        require_relative File.join('Stateful', 'Sequel')
+        klass.extend(Stateful::Sequel)
       else
         require_relative File.join('Stateful', 'Poro')
         klass.extend(Stateful::Poro)

data/stateful.rb.gemspec

@@ -0,0 +1,42 @@
+require_relative './lib/Stateful/VERSION'
+
+class Gem::Specification
+  def development_dependencies=(gems)
+    gems.each{|gem| add_development_dependency(*gem)}
+  end
+end
+
+Gem::Specification.new do |spec|
+  spec.name = 'stateful.rb'
+  spec.version = Stateful::VERSION
+
+  spec.summary = "A Ruby state machine."
+  spec.description = "Easily add state to Poro, ActiveRecord, and Sequel objects."
+
+  spec.author = 'thoran'
+  spec.email = 'code@thoran.com'
+  spec.homepage = 'http://github.com/thoran/stateful'
+  spec.license = 'MIT'
+
+  # The required version of Ruby is this higher than it strictly needs to be solely because the migrations have been made to require AR 6.0, but otherwise this should work with much lower versions of Ruby and ActiveRecord, even down to 2.3 (or lower) and AR 3 (or lower).
+  spec.required_ruby_version = '>= 2.5'
+
+  spec.require_paths = ['lib']
+
+  spec.files = [
+    'stateful.rb.gemspec',
+    'CHANGELOG.md',
+    'Gemfile',
+    'README.md',
+    Dir['lib/**/*.rb'],
+    Dir['test/**/*.rb']
+  ].flatten
+
+  spec.development_dependencies = %w{
+    minitest
+    minitest-spec-context
+    activerecord
+    sequel
+    sqlite3
+  }
+end