state_machines 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 2f3852a59e959d4add7fbde2dc0252eee9ac51a7
-  data.tar.gz: 41ee2c50b0bbcc40691cfe6ff13fed6ab5d14ce7
+SHA256:
+  metadata.gz: 1d22dcf0b70eca7cbf9a6894d592609874cfdef01474b70a2226018c0e8966b7
+  data.tar.gz: 9a9bed680181f45bc613649bf4f3b90a4ea1e198e8fb19f734d264c7652e5051
 SHA512:
-  metadata.gz: fa703fb24e2453a0fe96c386b83ab52a633698a8dd7b5d9de9afd48e3d9ee81c058e963d2a7546fe009266e50d22ecd9adfb9575fdb81ebe55dbe9ad166795ac
-  data.tar.gz: 5f74b1a302c64c4a0d6046decb74bb7e5e167f11bb3675795c6f53d46a2f235c7a91c31f9cd03b1e63c4246330b958937dd113413a2e8c96e6ce1e29f9759292
+  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,9 +1,11 @@
-[![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.png)](https://codeclimate.com/github/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
 
 State Machines adds support for creating state machines for attributes on any Ruby class.
 
+*Please note that multiple integrations are available for [Active Model](https://github.com/state-machines/state_machines-activemodel), [Active Record](https://github.com/state-machines/state_machines-activerecord), [Mongoid](https://github.com/state-machines/state_machines-mongoid) and more in the [State Machines organisation](https://github.com/state-machines).*  If you want to save state in your database, **you need one of these additional integrations**.
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -40,10 +42,10 @@ class Vehicle
   attr_accessor :seatbelt_on, :time_used, :auto_shop_busy
 
   state_machine :state, initial: :parked do
-    before_transition parked: :any - :parked, do: :put_on_seatbelt
-
+    before_transition parked: any - :parked, do: :put_on_seatbelt
+    
     after_transition on: :crash, do: :tow
-    after_transition on: :repair, :do: :fix
+    after_transition on: :repair, do: :fix
     after_transition any => :parked do |vehicle, transition|
       vehicle.seatbelt_on = false
     end
@@ -83,7 +85,7 @@ class Vehicle
     event :repair do
       # The first transition that matches the state and passes its conditions
       # will be used
-      transition stalled: parked, unless: :auto_shop_busy
+      transition stalled: :parked, unless: :auto_shop_busy
       transition stalled: same
     end
 
@@ -217,7 +219,7 @@ vehicle.fire_events(:shift_down, :enable_alarm) # => true
 vehicle.state_name                              # => :first_gear
 vehicle.alarm_state_name                        # => :active
 
-vehicle.fire_events!(:ignite, :enable_alarm)    # => StateMachines:InvalidTransition: Cannot run events in parallel: ignite, enable_alarm
+vehicle.fire_events!(:ignite, :enable_alarm)    # => StateMachines:InvalidParallelTransition: Cannot run events in parallel: ignite, enable_alarm
 
 # Human-friendly names can be accessed for states/events
 Vehicle.human_state_name(:first_gear)               # => "first gear"
@@ -235,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" ...>,
@@ -400,8 +406,8 @@ For example, transitions and callbacks can be defined like so:
 class Vehicle
   state_machine initial: :parked do
     before_transition from: :parked, except_to: :parked, do: :put_on_seatbelt
-    after_transition to: :parked do |transition|
-      self.seatbelt = 'off' # self is the record
+    after_transition to: :parked do |vehicle, transition|
+      vehicle.seatbelt = 'off'
     end
 
     event :ignite do
@@ -425,7 +431,7 @@ class Vehicle
     ...
 
     state :parked do
-      transition to::idling, :on => [:ignite, :shift_up], if: :seatbelt_on?
+      transition to: :idling, :on => [:ignite, :shift_up], if: :seatbelt_on?
 
       def speed
         0
@@ -463,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
@@ -561,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
@@ -575,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