state_machines 0.5.0 → 0.20.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: '029961fc61666a778298a5b6e5b5b31802b8710f'
-  data.tar.gz: d9e00ff04cbffbaf522e82b40e76aeb9c9ab3564
+SHA256:
+  metadata.gz: 5aa5d105c78cb53f15f42e8662dd7f8e0d0d5f8807b88dcbd8b4201f13718384
+  data.tar.gz: d761cedbe052c5c8829626e0875f54dce064f7156162119b4a040594b439068c
 SHA512:
-  metadata.gz: 52f6b57620f17c661585a1bccf2340d46be80366f2a7de609c41033ff46024cc62fc17814279267b26de65974612f149c0a057b47f2396e45f842c249742c9cd
-  data.tar.gz: b8bbe1923532edffd936139272782d6053b0ab8f1b338eaf61f805fbbc2a3b1c284bd523c35a375fc40fecb6f4948cb4aabcfc72c0fda5ded46959557a20b1cc
+  metadata.gz: 37398c9ca5f2de7413dfb7a8a467984d0fc4d47f8367ea0747fec6d9c1eaca5a7c3439f37988c02dd8ce27622a9a9e54cf5cc0b2d84404f00f92a862c168bb23
+  data.tar.gz: 159022534eb3c308bc2f2c8e960f111053631d3e10adafc9ae8156c95a26165f48690c682229a577bdfecf918b335ebe5b6d57e82e095c924585ad8d11b9d1ee

data/LICENSE.txt

@@ -1,5 +1,5 @@
 Copyright (c) 2006-2012 Aaron Pfeifer
-Copyright (c) 2014-2015 Abdelkader Boudih
+Copyright (c) 2014-2023 Abdelkader Boudih
 
 MIT License
 

data/README.md

@@ -1,5 +1,4 @@
-[![Build Status](https://travis-ci.org/state-machines/state_machines.svg?branch=master)](https://travis-ci.org/state-machines/state_machines)
-[![Code Climate](https://codeclimate.com/github/state-machines/state_machines.svg)](https://codeclimate.com/github/state-machines/state_machines)
+![Build Status](https://github.com/state-machines/state_machines/actions/workflows/ruby.yml/badge.svg)
 # State Machines
 
 State Machines adds support for creating state machines for attributes on any Ruby class.
@@ -237,6 +236,10 @@ vehicle.state_paths                                       # => [[#<StateMachines
 vehicle.state_paths.to_states                             # => [:parked, :idling, :first_gear, :stalled, :second_gear, :third_gear]
 vehicle.state_paths.events                                # => [:park, :ignite, :shift_up, :idle, :crash, :repair, :shift_down]
 
+# Possible states can be analyzed for a class
+Vehicle.state_machine.states.to_a                   # [#<StateMachines::State name=:parked value="parked" initial=true>, #<StateMachines::State name=:idling value="idling" initial=false>, ...]
+Vehicle.state_machines[:state].states.to_a          # [#<StateMachines::State name=:parked value="parked" initial=true>, #<StateMachines::State name=:idling value="idling" initial=false>, ...]
+
 # Find all paths that start and end on certain states
 vehicle.state_paths(:from => :parked, :to => :first_gear) # => [[
                                                           #       #<StateMachines:Transition attribute=:state event=:ignite from="parked" ...>,
@@ -251,6 +254,71 @@ vehicle.state_name              # => :parked
 # vehicle.state = :parked
 ```
 
+## Testing
+
+State Machines provides a `TestHelper` module with assertion methods to make testing state machines easier and more expressive.
+
+### Setup
+
+Include the test helper in your test class:
+
+```ruby
+# For Minitest
+class VehicleTest < Minitest::Test
+  include StateMachines::TestHelper
+  
+  def test_initial_state
+    vehicle = Vehicle.new
+    assert_state vehicle, :state, :parked
+  end
+end
+
+# For RSpec  
+RSpec.describe Vehicle do
+  include StateMachines::TestHelper
+  
+  it "starts in parked state" do
+    vehicle = Vehicle.new
+    assert_state vehicle, :state, :parked
+  end
+end
+```
+
+### Available Assertions
+
+The TestHelper provides both basic assertions and comprehensive state machine-specific assertions with `sm_` prefixes:
+
+#### Basic Assertions
+
+```ruby
+vehicle = Vehicle.new
+assert_state vehicle, :state, :parked
+assert_can_transition vehicle, :ignite
+assert_cannot_transition vehicle, :shift_up
+assert_transition vehicle, :ignite, :state, :idling
+```
+
+#### Extended State Machine Assertions
+
+```ruby
+machine = Vehicle.state_machine(:state)
+vehicle = Vehicle.new
+
+# State configuration
+assert_sm_states_list machine, [:parked, :idling, :stalled]
+assert_sm_initial_state machine, :parked
+
+# Event behavior  
+assert_sm_event_triggers vehicle, :ignite
+refute_sm_event_triggers vehicle, :shift_up
+assert_sm_event_raises_error vehicle, :invalid_event, StateMachines::InvalidTransition
+
+# Persistence (with ActiveRecord integration)
+assert_sm_state_persisted record, expected: :active
+```
+
+The test helper works with both Minitest and RSpec, automatically detecting your testing framework.
+
 ## Additional Topics
 
 ### Explicit vs. Implicit Event Transitions
@@ -424,7 +492,7 @@ easily migrate from a different library, you can do so as shown below:
 ```ruby
 class Vehicle
   state_machine initial: :parked do
-    ...
+    # ...
 
     state :parked do
       transition to: :idling, :on => [:ignite, :shift_up], if: :seatbelt_on?
@@ -460,12 +528,11 @@ example below:
 ```ruby
 class Vehicle
   state_machine initial: :parked do
-    ...
+    # ...
 
     transition parked: :idling, :on => [:ignite, :shift_up]
     transition first_gear: :second_gear, second_gear: :third_gear, on: :shift_up
     transition [:idling, :first_gear] => :parked, on: :park
-    transition [:idling, :first_gear] => :parked, on: :park
     transition all - [:parked, :stalled]: :stalled, unless: :auto_shop_busy?
   end
 end
@@ -493,12 +560,31 @@ class Vehicle
       transition [:idling, :first_gear] => :parked
     end
 
-    ...
+    # ...
   end
 end
 ```
 
-However, there may be cases where the definition of a state machine is **dynamic**.
+#### Draw state machines
+
+State machines includes a default STDIORenderer for debugging state machines without external dependencies.
+This renderer can be used to visualize the state machine in the console.
+
+To use the renderer, simply call the `draw` method on the state machine:
+
+```ruby
+Vehicle.state_machine.draw # Outputs the state machine diagram to the console
+```
+
+You can customize the output by passing in options to the `draw` method, such as the output stream:
+
+```ruby
+Vehicle.state_machine.draw(io: $stderr) # Outputs the state machine diagram to stderr
+```
+
+#### Dynamic definitions
+
+There may be cases where the definition of a state machine is **dynamic**.
 This means that you don't know the possible states or events for a machine until
 runtime.  For example, you may allow users in your application to manage the
 state machine of a project or task in your system.  This means that the list of
@@ -563,7 +649,7 @@ end
 vehicle = Vehicle.new                   # => #<Vehicle:0xb708412c @state="parked" ...>
 vehicle.state                           # => "parked"
 vehicle.machine.ignite                  # => true
-vehicle.machine.state                   # => "idling
+vehicle.machine.state                   # => "idling"
 vehicle.state                           # => "idling"
 vehicle.machine.state_transitions       # => [#<StateMachines:Transition ...>]
 vehicle.machine.definition.states.keys  # => :first_gear, :second_gear, :parked, :idling
@@ -577,22 +663,19 @@ transitions.
 
 Ruby versions officially supported and tested:
 
-* Ruby (MRI) 2.0.0+
-* JRuby
-* Rubinius
+* Ruby (MRI) 3.0.0+
 
 For graphing state machine:
 
-* [state_machines-graphviz](http://github.com/state-machines/state_machines-graphviz)
+* [state_machines-graphviz](https://github.com/state-machines/state_machines-graphviz)
 
 For documenting state machines:
 
-* [state_machines-yard](http://github.com/state-machines/state_machines-yard)
-
+* [state_machines-yard](https://github.com/state-machines/state_machines-yard)
 
-## TODO
+For RSpec testing, use the custom RSpec matchers:
 
-* Add matchers/assertions for rspec and minitest
+* [state_machines-rspec](https://github.com/state-machines/state_machines-rspec)
 
 ## Contributing
 

data/lib/state_machines/branch.rb

@@ -1,3 +1,7 @@
+# frozen_string_literal: true
+
+require_relative 'options_validator'
+
 module StateMachines
   # Represents a set of requirements that must be met in order for a transition
   # or callback to occur.  Branches verify that the event, from state, and to
@@ -6,68 +10,68 @@ module StateMachines
   class Branch
 
     include EvalHelpers
-    
+
     # The condition that must be met on an object
     attr_reader :if_condition
-    
+
     # The condition that must *not* be met on an object
     attr_reader :unless_condition
-    
+
     # The requirement for verifying the event being matched
     attr_reader :event_requirement
-    
+
     # One or more requirements for verifying the states being matched.  All
     # requirements contain a mapping of {:from => matcher, :to => matcher}.
     attr_reader :state_requirements
-    
+
     # A list of all of the states known to this branch.  This will pull states
     # from the following options (in the same order):
     # * +from+ / +except_from+
     # * +to+ / +except_to+
     attr_reader :known_states
-    
+
     # Creates a new branch
     def initialize(options = {}) #:nodoc:
       # Build conditionals
       @if_condition = options.delete(:if)
       @unless_condition = options.delete(:unless)
-      
+
       # Build event requirement
       @event_requirement = build_matcher(options, :on, :except_on)
-      
+
       if (options.keys - [:from, :to, :on, :except_from, :except_to, :except_on]).empty?
         # Explicit from/to requirements specified
-        @state_requirements = [{:from => build_matcher(options, :from, :except_from), :to => build_matcher(options, :to, :except_to)}]
+        @state_requirements = [{from: build_matcher(options, :from, :except_from), to: build_matcher(options, :to, :except_to)}]
       else
         # Separate out the event requirement
         options.delete(:on)
         options.delete(:except_on)
-        
+
         # Implicit from/to requirements specified
         @state_requirements = options.collect do |from, to|
           from = WhitelistMatcher.new(from) unless from.is_a?(Matcher)
           to = WhitelistMatcher.new(to) unless to.is_a?(Matcher)
-          {:from => from, :to => to}
+          {from: from, to: to}
         end
       end
-      
+
       # Track known states.  The order that requirements are iterated is based
       # on the priority in which tracked states should be added.
       @known_states = []
       @state_requirements.each do |state_requirement|
-        [:from, :to].each {|option| @known_states |= state_requirement[option].values}
+        [:from, :to].each { |option| @known_states |= state_requirement[option].values }
       end
     end
-    
+
     # Determines whether the given object / query matches the requirements
     # configured for this branch.  In addition to matching the event, from state,
     # and to state, this will also check whether the configured :if/:unless
     # conditions pass on the given object.
-    # 
+    #
     # == Examples
-    # 
+    #
     #   branch = StateMachines::Branch.new(:parked => :idling, :on => :ignite)
-    #   
+    #
     #   # Successful
     #   branch.matches?(object, :on => :ignite)                                   # => true
     #   branch.matches?(object, :from => nil)                                     # => true
@@ -75,7 +79,7 @@ module StateMachines
     #   branch.matches?(object, :to => :idling)                                   # => true
     #   branch.matches?(object, :from => :parked, :to => :idling)                 # => true
     #   branch.matches?(object, :on => :ignite, :from => :parked, :to => :idling) # => true
-    #   
+    #
     #   # Unsuccessful
     #   branch.matches?(object, :on => :park)                                     # => false
     #   branch.matches?(object, :from => :idling)                                 # => false
@@ -85,16 +89,16 @@ module StateMachines
     def matches?(object, query = {})
       !match(object, query).nil?
     end
-    
+
     # Attempts to match the given object / query against the set of requirements
     # configured for this branch.  In addition to matching the event, from state,
     # and to state, this will also check whether the configured :if/:unless
     # conditions pass on the given object.
-    # 
+    #
     # If a match is found, then the event/state requirements that the query
     # passed successfully will be returned.  Otherwise, nil is returned if there
     # was no match.
-    # 
+    #
     # Query options:
     # * <tt>:from</tt> - One or more states being transitioned from.  If none
     #   are specified, then this will always match.
@@ -104,80 +108,82 @@ module StateMachines
     #   are specified, then this will always match.
     # * <tt>:guard</tt> - Whether to guard matches with the if/unless
     #   conditionals defined for this branch.  Default is true.
-    # 
+    #
     # == Examples
-    # 
+    #
     #   branch = StateMachines::Branch.new(:parked => :idling, :on => :ignite)
-    #   
+    #
     #   branch.match(object, :on => :ignite)  # => {:to => ..., :from => ..., :on => ...}
     #   branch.match(object, :on => :park)    # => nil
     def match(object, query = {})
-      query.assert_valid_keys(:from, :to, :on, :guard)
-      
+      StateMachines::OptionsValidator.assert_valid_keys!(query, :from, :to, :on, :guard)
+
       if (match = match_query(query)) && matches_conditions?(object, query)
         match
       end
     end
 
-    def draw(graph, event, valid_states)
-     fail NotImplementedError
+    def draw(graph, event, valid_states, io = $stdout)
+      machine.renderer.draw_branch(self, graph, event, valid_states, io)
     end
-    
-    protected
-      # Builds a matcher strategy to use for the given options.  If neither a
-      # whitelist nor a blacklist option is specified, then an AllMatcher is
-      # built.
-      def build_matcher(options, whitelist_option, blacklist_option)
-        options.assert_exclusive_keys(whitelist_option, blacklist_option)
-        
-        if options.include?(whitelist_option)
-          value = options[whitelist_option]
-          value.is_a?(Matcher) ? value : WhitelistMatcher.new(options[whitelist_option])
-        elsif options.include?(blacklist_option)
-          value = options[blacklist_option]
-          raise ArgumentError, ":#{blacklist_option} option cannot use matchers; use :#{whitelist_option} instead" if value.is_a?(Matcher)
-          BlacklistMatcher.new(value)
-        else
-          AllMatcher.instance
-        end
-      end
-      
-      # Verifies that all configured requirements (event and state) match the
-      # given query.  If a match is found, then a hash containing the
-      # event/state requirements that passed will be returned; otherwise, nil.
-      def match_query(query)
-        query ||= {}
-        
-        if match_event(query) && (state_requirement = match_states(query))
-          state_requirement.merge(:on => event_requirement)
-        end
-      end
-      
-      # Verifies that the event requirement matches the given query
-      def match_event(query)
-        matches_requirement?(query, :on, event_requirement)
-      end
-      
-      # Verifies that the state requirements match the given query.  If a
-      # matching requirement is found, then it is returned.
-      def match_states(query)
-        state_requirements.detect do |state_requirement|
-          [:from, :to].all? {|option| matches_requirement?(query, option, state_requirement[option])}
-        end
+
+  protected
+
+    # Builds a matcher strategy to use for the given options.  If neither a
+    # whitelist nor a blacklist option is specified, then an AllMatcher is
+    # built.
+    def build_matcher(options, whitelist_option, blacklist_option)
+      StateMachines::OptionsValidator.assert_exclusive_keys!(options, whitelist_option, blacklist_option)
+
+      if options.include?(whitelist_option)
+        value = options[whitelist_option]
+        value.is_a?(Matcher) ? value : WhitelistMatcher.new(options[whitelist_option])
+      elsif options.include?(blacklist_option)
+        value = options[blacklist_option]
+        raise ArgumentError, ":#{blacklist_option} option cannot use matchers; use :#{whitelist_option} instead" if value.is_a?(Matcher)
+
+        BlacklistMatcher.new(value)
+      else
+        AllMatcher.instance
       end
-      
-      # Verifies that an option in the given query matches the values required
-      # for that option
-      def matches_requirement?(query, option, requirement)
-        !query.include?(option) || requirement.matches?(query[option], query)
+    end
+
+    # Verifies that all configured requirements (event and state) match the
+    # given query.  If a match is found, then a hash containing the
+    # event/state requirements that passed will be returned; otherwise, nil.
+    def match_query(query)
+      query ||= {}
+
+      if match_event(query) && (state_requirement = match_states(query))
+        state_requirement.merge(on: event_requirement)
       end
-      
-      # Verifies that the conditionals for this branch evaluate to true for the
-      # given object
-      def matches_conditions?(object, query)
-        query[:guard] == false ||
-        Array(if_condition).all? {|condition| evaluate_method(object, condition)} &&
-        !Array(unless_condition).any? {|condition| evaluate_method(object, condition)}
+    end
+
+    # Verifies that the event requirement matches the given query
+    def match_event(query)
+      matches_requirement?(query, :on, event_requirement)
+    end
+
+    # Verifies that the state requirements match the given query.  If a
+    # matching requirement is found, then it is returned.
+    def match_states(query)
+      state_requirements.detect do |state_requirement|
+        [:from, :to].all? { |option| matches_requirement?(query, option, state_requirement[option]) }
       end
+    end
+
+    # Verifies that an option in the given query matches the values required
+    # for that option
+    def matches_requirement?(query, option, requirement)
+      !query.include?(option) || requirement.matches?(query[option], query)
+    end
+
+    # Verifies that the conditionals for this branch evaluate to true for the
+    # given object
+    def matches_conditions?(object, query)
+      query[:guard] == false ||
+      Array(if_condition).all? { |condition| evaluate_method(object, condition) } &&
+      !Array(unless_condition).any? { |condition| evaluate_method(object, condition) }
+    end
   end
 end

data/lib/state_machines/callback.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'state_machines/branch'
 require 'state_machines/eval_helpers'
 
@@ -16,38 +18,38 @@ module StateMachines
       # the callback.  This can be configured on an application-wide basis by
       # setting this configuration to +true+ or +false+.  The default value
       # is +false+.
-      # 
+      #
       # *Note* that the DataMapper and Sequel integrations automatically
       # configure this value on a per-callback basis, so it does not have to
       # be enabled application-wide.
-      # 
+      #
       # == Examples
-      # 
+      #
       # When not bound to the object:
-      # 
+      #
       #   class Vehicle
       #     state_machine do
       #       before_transition do |vehicle|
       #         vehicle.set_alarm
       #       end
       #     end
-      #     
+      #
       #     def set_alarm
       #       ...
       #     end
       #   end
-      # 
+      #
       # When bound to the object:
-      # 
+      #
       #   StateMachines::Callback.bind_to_object = true
-      #   
+      #
       #   class Vehicle
       #     state_machine do
       #       before_transition do
       #         self.set_alarm
       #       end
       #     end
-      #     
+      #
       #     def set_alarm
       #       ...
       #     end
@@ -57,7 +59,7 @@ module StateMachines
       # The application-wide terminator to use for callbacks when not
       # explicitly defined.  Terminators determine whether to cancel a
       # callback chain based on the return value of the callback.
-      # 
+      #
       # See StateMachines::Callback#terminator for more information.
       attr_accessor :terminator
     end
@@ -75,11 +77,11 @@ module StateMachines
     # chain never cancels based on the return value (i.e. there is no implicit
     # terminator).  Certain integrations, such as ActiveRecord and Sequel,
     # change this default value.
-    # 
+    #
     # == Examples
-    # 
+    #
     # Canceling the callback chain without a terminator:
-    # 
+    #
     #   class Vehicle
     #     state_machine do
     #       before_transition do |vehicle|
@@ -87,9 +89,9 @@ module StateMachines
     #       end
     #     end
     #   end
-    # 
+    #
     # Canceling the callback chain with a terminator value of +false+:
-    # 
+    #
     #   class Vehicle
     #     state_machine do
     #       before_transition do |vehicle|
@@ -102,13 +104,13 @@ module StateMachines
     # The branch that determines whether or not this callback can be invoked
     # based on the context of the transition.  The event, from state, and
     # to state must all match in order for the branch to pass.
-    # 
+    #
     # See StateMachines::Branch for more information.
     attr_reader :branch
 
     # Creates a new callback that can get called based on the configured
     # options.
-    # 
+    #
     # In addition to the possible configuration options for branches, the
     # following options can be configured:
     # * <tt>:bind_to_object</tt> - Whether to bind the callback to the object involved.
@@ -117,7 +119,7 @@ module StateMachines
     # * <tt>:terminator</tt> - A block/proc that determines what callback
     #   results should cause the callback chain to halt (if not using the
     #   default <tt>throw :halt</tt> technique).
-    # 
+    #
     # More information about how those options affect the behavior of the
     # callback can be found in their attribute definitions.
     def initialize(type, *args, &block)
@@ -130,7 +132,7 @@ module StateMachines
       @methods << block if block_given?
       raise ArgumentError, 'Method(s) for callback must be specified' unless @methods.any?
 
-      options = {:bind_to_object => self.class.bind_to_object, :terminator => self.class.terminator}.merge(options)
+      options = {bind_to_object: self.class.bind_to_object, terminator: self.class.terminator}.merge(options)
 
       # Proxy lambda blocks so that they're bound to the object
       bind_to_object = options.delete(:bind_to_object)
@@ -151,7 +153,7 @@ module StateMachines
     # Runs the callback as long as the transition context matches the branch
     # requirements configured for this callback.  If a block is provided, it
     # will be called when the last method has run.
-    # 
+    #
     # If a terminator has been configured and it matches the result from the
     # evaluated method, then the callback chain should be halted.
     def call(object, context = {}, *args, &block)
@@ -163,7 +165,8 @@ module StateMachines
       end
     end
 
-    private
+  private
+
     # Runs all of the methods configured for this callback.
     #
     # When running +around+ callbacks, this will evaluate each method and

data/lib/state_machines/core.rb

@@ -1,9 +1,10 @@
+# frozen_string_literal: true
+
 # Load all of the core implementation required to use state_machine.  This
 # includes:
 # * StateMachines::MacroMethods which adds the state_machine DSL to your class
 # * A set of initializers for setting state_machine defaults based on the current
 #   running environment (such as within Rails)
-require 'state_machines/assertions'
 require 'state_machines/error'
 
 require 'state_machines/extensions'
@@ -40,4 +41,4 @@ require 'state_machines/path_collection'
 require 'state_machines/machine'
 require 'state_machines/machine_collection'
 
-require 'state_machines/macro_methods'
+require 'state_machines/macro_methods'

data/lib/state_machines/core_ext/class/state_machine.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 Class.class_eval do
   include StateMachines::MacroMethods
 end

data/lib/state_machines/core_ext.rb

@@ -1,2 +1,4 @@
+# frozen_string_literal: true
+
 # Loads all of the extensions to be made to Ruby core classes
 require 'state_machines/core_ext/class/state_machine'

data/lib/state_machines/error.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module StateMachines
   # An error occurred during a state machine invocation
   class Error < StandardError