state_machines 0.5.0 → 0.50.0

data/lib/state_machines/branch.rb

@@ -1,73 +1,82 @@
+# 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
   # state of the transition match, in addition to if/unless conditionals for
   # an object's state.
   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:
+    def initialize(options = {}) # :nodoc:
       # Build conditionals
       @if_condition = options.delete(:if)
       @unless_condition = options.delete(:unless)
-      
+      @if_state_condition = options.delete(:if_state)
+      @unless_state_condition = options.delete(:unless_state)
+      @if_all_states_condition = options.delete(:if_all_states)
+      @unless_all_states_condition = options.delete(:unless_all_states)
+      @if_any_state_condition = options.delete(:if_any_state)
+      @unless_any_state_condition = options.delete(:unless_any_state)
+
       # Build event requirement
       @event_requirement = build_matcher(options, :on, :except_on)
-      
-      if (options.keys - [:from, :to, :on, :except_from, :except_to, :except_on]).empty?
+
+      if (options.keys - %i[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}
+        %i[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 +84,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 +94,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 +113,131 @@ 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.
-    # 
+    #
+    # Event arguments are passed to guard conditions if they accept multiple parameters.
+    #
     # == 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
+    def match(object, query = {}, event_args = [])
+      StateMachines::OptionsValidator.assert_valid_keys!(query, :from, :to, :on, :guard)
+
+      return unless (match = match_query(query)) && matches_conditions?(object, query, event_args)
+
+      match
     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
+
+    # 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 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 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 event requirement matches the given query
-      def match_event(query)
-        matches_requirement?(query, :on, event_requirement)
+    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|
+        %i[from to].all? { |option| matches_requirement?(query, option, state_requirement[option]) }
       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
+
+    # 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. Event arguments are passed to guards that accept multiple parameters.
+    def matches_conditions?(object, query, event_args = [])
+      return true if query[:guard] == false
+
+      # Evaluate original if/unless conditions
+      if_passes = !if_condition || Array(if_condition).all? { |condition| evaluate_method_with_event_args(object, condition, event_args) }
+      unless_passes = !unless_condition || Array(unless_condition).none? { |condition| evaluate_method_with_event_args(object, condition, event_args) }
+
+      return false unless if_passes && unless_passes
+
+      # Consolidate all state guards
+      state_guards = {
+        if_state: @if_state_condition,
+        unless_state: @unless_state_condition,
+        if_all_states: @if_all_states_condition,
+        unless_all_states: @unless_all_states_condition,
+        if_any_state: @if_any_state_condition,
+        unless_any_state: @unless_any_state_condition
+      }.compact
+
+      return true if state_guards.empty?
+
+      validate_and_check_state_guards(object, state_guards)
+    end
+
+    private
+
+    def validate_and_check_state_guards(object, guards)
+      guards.all? do |guard_type, conditions|
+        case guard_type
+        when :if_state, :if_all_states
+          conditions.all? { |machine, state| check_state(object, machine, state) }
+        when :unless_state
+          conditions.none? { |machine, state| check_state(object, machine, state) }
+        when :if_any_state
+          conditions.any? { |machine, state| check_state(object, machine, state) }
+        when :unless_all_states
+          !conditions.all? { |machine, state| check_state(object, machine, state) }
+        when :unless_any_state
+          conditions.none? { |machine, state| check_state(object, machine, state) }
         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
+
+    def check_state(object, machine_name, state_name)
+      machine = object.class.state_machines[machine_name]
+      raise ArgumentError, "State machine '#{machine_name}' is not defined for #{object.class.name}" unless machine
+
+      state = machine.states[state_name]
+      raise ArgumentError, "State '#{state_name}' is not defined in state machine '#{machine_name}'" unless state
+
+      state.matches?(object.send(machine_name))
+    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,12 +119,12 @@ 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)
       @type = type
-      raise ArgumentError, 'Type must be :before, :after, :around, or :failure' unless [:before, :after, :around, :failure].include?(type)
+      raise ArgumentError, 'Type must be :before, :after, :around, or :failure' unless %i[before after around failure].include?(type)
 
       options = args.last.is_a?(Hash) ? args.pop : {}
       @methods = args
@@ -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,12 +153,12 @@ 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)
+    def call(object, context = {}, *, &)
       if @branch.matches?(object, context)
-        run_methods(object, context, 0, *args, &block)
+        run_methods(object, context, 0, *, &)
         true
       else
         false
@@ -164,6 +166,7 @@ module StateMachines
     end
 
     private
+
     # Runs all of the methods configured for this callback.
     #
     # When running +around+ callbacks, this will evaluate each method and
@@ -174,9 +177,10 @@ module StateMachines
     # order.  The callback will only halt if the resulting value from the
     # method passes the terminator.
     def run_methods(object, context = {}, index = 0, *args, &block)
-      if type == :around
+      case type
+      when :around
         current_method = @methods[index]
-        if  current_method
+        if current_method
           yielded = false
           evaluate_method(object, current_method, *args) do
             yielded = true
@@ -184,13 +188,13 @@ module StateMachines
           end
 
           throw :halt unless yielded
-        else
-          yield if block_given?
+        elsif block_given?
+          yield
         end
       else
         @methods.each do |method|
           result = evaluate_method(object, method, *args)
-          throw :halt if @terminator && @terminator.call(result)
+          throw :halt if @terminator&.call(result)
         end
       end
     end
@@ -203,13 +207,12 @@ module StateMachines
       arity += 1 if arity >= 0 # Make sure the object gets passed
       arity += 1 if arity == 1 && type == :around # Make sure the block gets passed
 
-      method = lambda { |object, *args| object.instance_exec(*args, &block) }
-
+      method = ->(object, *args) { object.instance_exec(*args, &block) }
 
       # Proxy arity to the original block
       (
-      class << method;
-        self;
+      class << method
+        self
       end).class_eval do
         define_method(:arity) { arity }
       end

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'
@@ -23,7 +24,6 @@ require 'state_machines/transition_collection'
 require 'state_machines/branch'
 
 require 'state_machines/helper_module'
-require 'state_machines/state'
 require 'state_machines/callback'
 require 'state_machines/node_collection'
 
@@ -40,4 +40,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,10 +1,12 @@
+# frozen_string_literal: true
+
 module StateMachines
   # An error occurred during a state machine invocation
   class Error < StandardError
     # The object that failed
     attr_reader :object
 
-    def initialize(object, message = nil) #:nodoc:
+    def initialize(object, message = nil) # :nodoc:
       @object = object
 
       super(message)
@@ -47,12 +49,13 @@ module StateMachines
     # The event that was attempted to be run
     attr_reader :event
 
-    def initialize(object, event_name) #:nodoc:
+    def initialize(object, event_name) # :nodoc:
       @event = event_name
 
       super(object, "#{event.inspect} is an unknown state machine event")
     end
   end
+
   # An invalid transition was attempted
   class InvalidTransition < Error
     # The machine attempting to be transitioned
@@ -61,7 +64,7 @@ module StateMachines
     # The current state value for the machine
     attr_reader :from
 
-    def initialize(object, machine, event) #:nodoc:
+    def initialize(object, machine, event) # :nodoc:
       @machine = machine
       @from_state = machine.states.match!(object)
       @from = machine.read(object, :state)
@@ -99,7 +102,7 @@ module StateMachines
     # The set of events that failed the transition(s)
     attr_reader :events
 
-    def initialize(object, events) #:nodoc:
+    def initialize(object, events) # :nodoc:
       @events = events
 
       super(object, "Cannot run events in parallel: #{events * ', '}")