state_machines 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: '029961fc61666a778298a5b6e5b5b31802b8710f'
-  data.tar.gz: d9e00ff04cbffbaf522e82b40e76aeb9c9ab3564
+SHA256:
+  metadata.gz: 1d22dcf0b70eca7cbf9a6894d592609874cfdef01474b70a2226018c0e8966b7
+  data.tar.gz: 9a9bed680181f45bc613649bf4f3b90a4ea1e198e8fb19f734d264c7652e5051
 SHA512:
-  metadata.gz: 52f6b57620f17c661585a1bccf2340d46be80366f2a7de609c41033ff46024cc62fc17814279267b26de65974612f149c0a057b47f2396e45f842c249742c9cd
-  data.tar.gz: b8bbe1923532edffd936139272782d6053b0ab8f1b338eaf61f805fbbc2a3b1c284bd523c35a375fc40fecb6f4948cb4aabcfc72c0fda5ded46959557a20b1cc
+  metadata.gz: d1446488cbb427e407611d2cba2e571401931a4a20f9f8655e14ebf896990468d24a94a02ba708627db8beb3a3821ac481b220551f0d0c02e366ba3d78112da4
+  data.tar.gz: 4949561813ac58b6442611d37083091b6c4532f41227f3f9f0999bbecc18c18aacc458f9aa6d6570b5855b6a30a24394d421e6b6012dfa4ebed638a642da82f3

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,4 +1,4 @@
-[![Build Status](https://travis-ci.org/state-machines/state_machines.svg?branch=master)](https://travis-ci.org/state-machines/state_machines)
+![Build Status](https://github.com/state-machines/state_machines/actions/workflows/ruby.yml/badge.svg)
 [![Code Climate](https://codeclimate.com/github/state-machines/state_machines.svg)](https://codeclimate.com/github/state-machines/state_machines)
 # State Machines
 
@@ -237,6 +237,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" ...>,
@@ -465,7 +469,6 @@ class Vehicle
     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
@@ -563,7 +566,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,7 +580,7 @@ transitions.
 
 Ruby versions officially supported and tested:
 
-* Ruby (MRI) 2.0.0+
+* Ruby (MRI) 2.6.0+
 * JRuby
 * Rubinius
 

data/lib/state_machines/branch.rb

@@ -6,68 +6,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 +75,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 +85,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,16 +104,16 @@ 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)
-      
+
       if (match = match_query(query)) && matches_conditions?(object, query)
         match
       end
@@ -122,62 +122,64 @@ module StateMachines
     def draw(graph, event, valid_states)
      fail NotImplementedError
     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)
+      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
-      
-      # 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

@@ -16,38 +16,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 +57,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 +75,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 +87,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 +102,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 +117,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 +130,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 +151,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 +163,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/eval_helpers.rb

@@ -7,46 +7,46 @@ module StateMachines
     # * Symbol
     # * Method / Proc
     # * String
-    # 
+    #
     # == Examples
-    # 
+    #
     # Below are examples of the various ways that a method can be evaluated
     # on an object:
-    # 
+    #
     #   class Person
     #     def initialize(name)
     #       @name = name
     #     end
-    #     
+    #
     #     def name
     #       @name
     #     end
     #   end
-    #   
+    #
     #   class PersonCallback
     #     def self.run(person)
     #       person.name
     #     end
     #   end
-    # 
+    #
     #   person = Person.new('John Smith')
-    #   
+    #
     #   evaluate_method(person, :name)                            # => "John Smith"
     #   evaluate_method(person, PersonCallback.method(:run))      # => "John Smith"
     #   evaluate_method(person, Proc.new {|person| person.name})  # => "John Smith"
     #   evaluate_method(person, lambda {|person| person.name})    # => "John Smith"
     #   evaluate_method(person, '@name')                          # => "John Smith"
-    # 
+    #
     # == Additional arguments
-    # 
+    #
     # Additional arguments can be passed to the methods being evaluated.  If
     # the method defines additional arguments other than the object context,
     # then all arguments are required.
-    # 
+    #
     # For example,
-    # 
+    #
     #   person = Person.new('John Smith')
-    #   
+    #
     #   evaluate_method(person, lambda {|person| person.name}, 21)                              # => "John Smith"
     #   evaluate_method(person, lambda {|person, age| "#{person.name} is #{age}"}, 21)          # => "John Smith is 21"
     #   evaluate_method(person, lambda {|person, age| "#{person.name} is #{age}"}, 21, 'male')  # => ArgumentError: wrong number of arguments (3 for 2)
@@ -59,7 +59,7 @@ module StateMachines
         when Proc, Method
           args.unshift(object)
           arity = method.arity
-          
+
           # Procs don't support blocks in < Ruby 1.9, so it's tacked on as an
           # argument for consistency across versions of Ruby
           if block_given? && Proc === method && arity != 0
@@ -75,10 +75,10 @@ module StateMachines
             # These method types are only called with 0, 1, or n arguments
             args = args[0, arity] if [0, 1].include?(arity)
           end
-          
+
           method.is_a?(Proc) ? method.call(*args) : method.call(*args, &block)
         when String
-          eval(method, object.instance_eval {binding}, &block)
+          eval(method, object.instance_eval { binding }, &block)
         else
           raise ArgumentError, 'Methods must be a symbol denoting the method to call, a block to be invoked, or a string to be evaluated'
       end