state_machines 0.5.0 → 0.20.0

data/lib/state_machines/matcher.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module StateMachines
   # Provides a general strategy pattern for determining whether a match is found
   # for a value.  The algorithm that actually determines the match depends on
@@ -5,114 +7,115 @@ module StateMachines
   class Matcher
     # The list of values against which queries are matched
     attr_reader :values
-    
+
     # Creates a new matcher for querying against the given set of values
     def initialize(values = [])
       @values = values.is_a?(Array) ? values : [values]
     end
-    
+
     # Generates a subset of values that exists in both the set of values being
     # filtered and the values configured for the matcher
     def filter(values)
       self.values & values
     end
   end
-  
+
   # Matches any given value.  Since there is no configuration for this type of
   # matcher, it must be used as a singleton.
   class AllMatcher < Matcher
     include Singleton
-    
+
     # Generates a blacklist matcher based on the given set of values
-    # 
+    #
     # == Examples
-    # 
+    #
     #   matcher = StateMachines::AllMatcher.instance - [:parked, :idling]
     #   matcher.matches?(:parked)       # => false
     #   matcher.matches?(:first_gear)   # => true
     def -(blacklist)
       BlacklistMatcher.new(blacklist)
     end
-    
+    alias_method :except, :-
+
     # Always returns true
     def matches?(value, context = {})
       true
     end
-    
+
     # Always returns the given set of values
     def filter(values)
       values
     end
-    
+
     # A human-readable description of this matcher.  Always "all".
     def description
       'all'
     end
   end
-  
+
   # Matches a specific set of values
   class WhitelistMatcher < Matcher
     # Checks whether the given value exists within the whitelist configured
     # for this matcher.
-    # 
+    #
     # == Examples
-    # 
+    #
     #   matcher = StateMachines::WhitelistMatcher.new([:parked, :idling])
     #   matcher.matches?(:parked)       # => true
     #   matcher.matches?(:first_gear)   # => false
     def matches?(value, context = {})
       values.include?(value)
     end
-    
+
     # A human-readable description of this matcher
     def description
       values.length == 1 ? values.first.inspect : values.inspect
     end
   end
-  
+
   # Matches everything but a specific set of values
   class BlacklistMatcher < Matcher
     # Checks whether the given value exists outside the blacklist configured
     # for this matcher.
-    # 
+    #
     # == Examples
-    # 
+    #
     #   matcher = StateMachines::BlacklistMatcher.new([:parked, :idling])
     #   matcher.matches?(:parked)       # => false
     #   matcher.matches?(:first_gear)   # => true
     def matches?(value, context = {})
       !values.include?(value)
     end
-    
+
     # Finds all values that are *not* within the blacklist configured for this
     # matcher
     def filter(values)
       values - self.values
     end
-    
+
     # A human-readable description of this matcher
     def description
       "all - #{values.length == 1 ? values.first.inspect : values.inspect}"
     end
   end
-  
+
   # Matches a loopback of two values within a context.  Since there is no
   # configuration for this type of matcher, it must be used as a singleton.
   class LoopbackMatcher < Matcher
     include Singleton
-    
+
     # Checks whether the given value matches what the value originally was.
     # This value should be defined in the context.
-    # 
+    #
     # == Examples
-    # 
+    #
     #   matcher = StateMachines::LoopbackMatcher.instance
     #   matcher.matches?(:parked, :from => :parked)   # => true
     #   matcher.matches?(:parked, :from => :idling)   # => false
     def matches?(value, context)
       context[:from] == value
     end
-    
+
     # A human-readable description of this matcher.  Always "same".
     def description
       'same'

data/lib/state_machines/matcher_helpers.rb

@@ -1,25 +1,27 @@
+# frozen_string_literal: true
+
 module StateMachines
   # Provides a set of helper methods for generating matchers
   module MatcherHelpers
     # Represents a state that matches all known states in a machine.
-    # 
+    #
     # == Examples
-    # 
+    #
     #   class Vehicle
     #     state_machine do
     #       before_transition any => :parked, :do => lambda {...}
     #       before_transition all - :parked => all - :idling, :do => lambda {}
-    #       
+    #
     #       event :park
     #         transition all => :parked
     #       end
-    #       
+    #
     #       event :crash
     #         transition all - :parked => :stalled
     #       end
     #     end
     #   end
-    # 
+    #
     # In the above example, +all+ will match the following states since they
     # are known:
     # * +parked+
@@ -29,12 +31,12 @@ module StateMachines
       AllMatcher.instance
     end
     alias_method :any, :all
-    
+
     # Represents a state that matches the original +from+ state.  This is useful
     # for defining transitions which are loopbacks.
-    # 
+    #
     # == Examples
-    # 
+    #
     #   class Vehicle
     #     state_machine do
     #       event :ignite
@@ -42,11 +44,11 @@ module StateMachines
     #       end
     #     end
     #   end
-    # 
+    #
     # In the above example, +same+ will match whichever the from state is.  In
     # the case of the +ignite+ event, it is essential the same as the following:
-    # 
-    #   transition :parked => :parked, :first_gear => :first_gear
+    #
+    #   transition :idling => :idling, :first_gear => :first_gear
     def same
       LoopbackMatcher.instance
     end

data/lib/state_machines/node_collection.rb

@@ -1,3 +1,7 @@
+# frozen_string_literal: true
+
+require_relative 'options_validator'
+
 module StateMachines
   # Represents a collection of nodes in a state machine, be it events or states.
   # Nodes will not differentiate between the String and Symbol versions of the
@@ -16,7 +20,7 @@ module StateMachines
     #   hashed indices for in order to perform quick lookups.  Default is to
     #   index by the :name attribute
     def initialize(machine, options = {})
-      options.assert_valid_keys(:index)
+      StateMachines::OptionsValidator.assert_valid_keys!(options, :index)
       options = { index: :name }.merge(options)
 
       @machine = machine
@@ -162,37 +166,39 @@ module StateMachines
       self[key, index_name] || fail(IndexError, "#{key.inspect} is an invalid #{index_name}")
     end
 
-    protected
-      # Gets the given index.  If the index does not exist, then an ArgumentError
-      # is raised.
+  protected
+
+    # Gets the given index.  If the index does not exist, then an ArgumentError
+    # is raised.
     def index(name)
       fail ArgumentError, 'No indices configured' unless @indices.any?
+
       @indices[name] || fail(ArgumentError, "Invalid index: #{name.inspect}")
     end
 
-      # Gets the value for the given attribute on the node
+    # Gets the value for the given attribute on the node
     def value(node, attribute)
       node.send(attribute)
     end
 
-      # Adds the given key / node combination to an index, including the string
-      # and symbol versions of the index
+    # Adds the given key / node combination to an index, including the string
+    # and symbol versions of the index
     def add_to_index(name, key, node)
       index(name)[key] = node
       index(:"#{name}_to_s")[key.to_s] = node
       index(:"#{name}_to_sym")[:"#{key}"] = node if to_sym?(key)
     end
 
-      # Removes the given key from an index, including the string and symbol
-      # versions of the index
+    # Removes the given key from an index, including the string and symbol
+    # versions of the index
     def remove_from_index(name, key)
       index(name).delete(key)
       index(:"#{name}_to_s").delete(key.to_s)
       index(:"#{name}_to_sym").delete(:"#{key}") if to_sym?(key)
     end
 
-      # Updates the node for the given index, including the string and symbol
-      # versions of the index
+    # Updates the node for the given index, including the string and symbol
+    # versions of the index
     def update_index(name, node)
       index = self.index(name)
       old_key = index.key(node)
@@ -205,13 +211,13 @@ module StateMachines
       end
     end
 
-      # Determines whether the given value can be converted to a symbol
+    # Determines whether the given value can be converted to a symbol
     def to_sym?(value)
       "#{value}" != ''
     end
 
-      # Evaluates the given context for a particular node.  This will only
-      # evaluate the context if the node matches.
+    # Evaluates the given context for a particular node.  This will only
+    # evaluate the context if the node matches.
     def eval_context(context, node)
       node.context(&context[:block]) if context[:nodes].matches?(node.name)
     end

data/lib/state_machines/options_validator.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module StateMachines
+  # Define the module if it doesn't exist yet
+  # Module for validating options without monkey-patching Hash
+  # Provides the same functionality as the Hash monkey patch but in a cleaner way
+  module OptionsValidator
+    class << self
+      # Validates that all keys in the options hash are in the list of valid keys
+      #
+      # @param options [Hash] The options hash to validate
+      # @param valid_keys [Array<Symbol>] List of valid key names
+      # @param caller_info [String] Information about the calling method for better error messages
+      # @raise [ArgumentError] If any invalid keys are found
+      def assert_valid_keys!(options, *valid_keys, caller_info: nil)
+        return if options.empty?
+
+        valid_keys.flatten!
+        invalid_keys = options.keys - valid_keys
+
+        return if invalid_keys.empty?
+
+        caller_context = caller_info ? " in #{caller_info}" : ''
+        raise ArgumentError, "Unknown key#{'s' if invalid_keys.length > 1}: #{invalid_keys.map(&:inspect).join(', ')}. Valid keys are: #{valid_keys.map(&:inspect).join(', ')}#{caller_context}"
+      end
+
+      # Validates that at most one of the exclusive keys is present in the options hash
+      #
+      # @param options [Hash] The options hash to validate
+      # @param exclusive_keys [Array<Symbol>] List of mutually exclusive keys
+      # @param caller_info [String] Information about the calling method for better error messages
+      # @raise [ArgumentError] If more than one exclusive key is found
+      def assert_exclusive_keys!(options, *exclusive_keys, caller_info: nil)
+        return if options.empty?
+
+        conflicting_keys = exclusive_keys & options.keys
+        return if conflicting_keys.length <= 1
+
+        caller_context = caller_info ? " in #{caller_info}" : ''
+        raise ArgumentError, "Conflicting keys: #{conflicting_keys.join(', ')}#{caller_context}"
+      end
+
+      # Validates options using a more convenient interface that works with both
+      # hash-style and kwargs-style method definitions
+      #
+      # @param valid_keys [Array<Symbol>] List of valid key names
+      # @param exclusive_key_groups [Array<Array<Symbol>>] Groups of mutually exclusive keys
+      # @param caller_info [String] Information about the calling method
+      # @return [Proc] A validation proc that can be called with options
+      def validator(valid_keys: [], exclusive_key_groups: [], caller_info: nil)
+        proc do |options|
+          assert_valid_keys!(options, *valid_keys, caller_info: caller_info) unless valid_keys.empty?
+
+          exclusive_key_groups.each do |group|
+            assert_exclusive_keys!(options, *group, caller_info: caller_info)
+          end
+        end
+      end
+
+      # Helper method for backwards compatibility - allows gradual migration
+      # from Hash monkey patch to this module
+      #
+      # @param options [Hash] The options to validate
+      # @param valid_keys [Array<Symbol>] Valid keys
+      # @return [Hash] The same options hash (for chaining)
+      def validate_and_return(options, *valid_keys)
+        assert_valid_keys!(options, *valid_keys)
+        options
+      end
+    end
+  end
+end

data/lib/state_machines/path.rb

@@ -1,82 +1,86 @@
+# frozen_string_literal: true
+
+require_relative 'options_validator'
+
 module StateMachines
   # A path represents a sequence of transitions that can be run for a particular
   # object.  Paths can walk to new transitions, revealing all of the possible
   # branches that can be encountered in the object's state machine.
   class Path < Array
 
-    
+
     # The object whose state machine is being walked
     attr_reader :object
-    
+
     # The state machine this path is walking
     attr_reader :machine
-    
+
     # Creates a new transition path for the given object.  Initially this is an
     # empty path.  In order to start walking the path, it must be populated with
     # an initial transition.
-    # 
+    #
     # Configuration options:
     # * <tt>:target</tt> - The target state to end the path on
     # * <tt>:guard</tt> - Whether to guard transitions with the if/unless
     #   conditionals defined for each one
     def initialize(object, machine, options = {})
-      options.assert_valid_keys(:target, :guard)
-      
+      StateMachines::OptionsValidator.assert_valid_keys!(options, :target, :guard)
+
       @object = object
       @machine = machine
       @target = options[:target]
       @guard = options[:guard]
     end
-    
+
     def initialize_copy(orig) #:nodoc:
       super
       @transitions = nil
     end
-    
+
     # The initial state name for this path
     def from_name
-      first && first.from_name
+      first&.from_name
     end
-    
+
     # Lists all of the from states that can be reached through this path.
-    # 
+    #
     # For example,
-    # 
+    #
     #   path.to_states  # => [:parked, :idling, :first_gear, ...]
     def from_states
-      map {|transition| transition.from_name}.uniq
+      map { |transition| transition.from_name }.uniq
     end
-    
+
     # The end state name for this path.  If a target state was specified for
     # the path, then that will be returned if the path is complete.
     def to_name
-      last && last.to_name
+      last&.to_name
     end
-    
+
     # Lists all of the to states that can be reached through this path.
-    # 
+    #
     # For example,
-    # 
+    #
     #   path.to_states  # => [:parked, :idling, :first_gear, ...]
     def to_states
-      map {|transition| transition.to_name}.uniq
+      map { |transition| transition.to_name }.uniq
     end
-    
+
     # Lists all of the events that can be fired through this path.
-    # 
+    #
     # For example,
-    # 
+    #
     #   path.events # => [:park, :ignite, :shift_up, ...]
     def events
-      map {|transition| transition.event}.uniq
+      map { |transition| transition.event }.uniq
     end
-    
+
     # Walks down the next transitions at the end of this path.  This will only
     # walk down paths that are considered valid.
     def walk
-      transitions.each {|transition| yield dup.push(transition)}
+      transitions.each { |transition| yield dup.push(transition) }
     end
-    
+
     # Determines whether or not this path has completed.  A path is considered
     # complete when one of the following conditions is met:
     # * The last transition in the path ends on the target state
@@ -85,36 +89,37 @@ module StateMachines
     def complete?
       !empty? && (@target ? to_name == @target : transitions.empty?)
     end
-    
-    private
-      # Calculates the number of times the given state has been walked to
-      def times_walked_to(state)
-        select {|transition| transition.to_name == state}.length
-      end
-      
-      # Determines whether the given transition has been recently walked down in
-      # this path.  If a target is configured for this path, then this will only
-      # look at transitions walked down since the target was last reached.
-      def recently_walked?(transition)
-        transitions = self
-        if @target && @target != to_name && target_transition = detect {|t| t.to_name == @target}
-          transitions = transitions[index(target_transition) + 1..-1]
-        end
-        transitions.include?(transition)
-      end
-      
-      # Determines whether it's possible to walk to the given transition from
-      # the current path.  A transition can be walked to if:
-      # * It has not been recently walked and
-      # * If a target is specified, it has not been walked to twice yet
-      def can_walk_to?(transition)
-        !recently_walked?(transition) && (!@target || times_walked_to(@target) < 2)
-      end
-      
-      # Get the next set of transitions that can be walked to starting from the
-      # end of this path
-      def transitions
-        @transitions ||= empty? ? [] : machine.events.transitions_for(object, :from => to_name, :guard => @guard).select {|transition| can_walk_to?(transition)}
+
+  private
+
+    # Calculates the number of times the given state has been walked to
+    def times_walked_to(state)
+      select { |transition| transition.to_name == state }.length
+    end
+
+    # Determines whether the given transition has been recently walked down in
+    # this path.  If a target is configured for this path, then this will only
+    # look at transitions walked down since the target was last reached.
+    def recently_walked?(transition)
+      transitions = self
+      if @target && @target != to_name && (target_transition = detect { |t| t.to_name == @target })
+        transitions = transitions[index(target_transition) + 1..-1]
       end
+      transitions.include?(transition)
+    end
+
+    # Determines whether it's possible to walk to the given transition from
+    # the current path.  A transition can be walked to if:
+    # * It has not been recently walked and
+    # * If a target is specified, it has not been walked to twice yet
+    def can_walk_to?(transition)
+      !recently_walked?(transition) && (!@target || times_walked_to(@target) < 2)
+    end
+
+    # Get the next set of transitions that can be walked to starting from the
+    # end of this path
+    def transitions
+      @transitions ||= empty? ? [] : machine.events.transitions_for(object, from: to_name, guard: @guard).select { |transition| can_walk_to?(transition) }
+    end
   end
 end

data/lib/state_machines/path_collection.rb

@@ -1,23 +1,26 @@
+# frozen_string_literal: true
+
+require_relative 'options_validator'
+
 module StateMachines
   # Represents a collection of paths that are generated based on a set of
   # requirements regarding what states to start and end on
   class PathCollection < Array
 
-    
     # The object whose state machine is being walked
     attr_reader :object
-    
+
     # The state machine these path are walking
     attr_reader :machine
-    
+
     # The initial state to start each path from
     attr_reader :from_name
-    
+
     # The target state for each path
     attr_reader :to_name
-    
+
     # Creates a new collection of paths with the given requirements.
-    # 
+    #
     # Configuration options:
     # * <tt>:from</tt> - The initial state to start from
     # * <tt>:to</tt> - The target end state
@@ -25,64 +28,65 @@ module StateMachines
     # * <tt>:guard</tt> - Whether to guard transitions with the if/unless
     #   conditionals defined for each one
     def initialize(object, machine, options = {})
-      options = {:deep => false, :from => machine.states.match!(object).name}.merge(options)
-      options.assert_valid_keys( :from, :to, :deep, :guard)
-      
+      options = {deep: false, from: machine.states.match!(object).name}.merge(options)
+      StateMachines::OptionsValidator.assert_valid_keys!(options, :from, :to, :deep, :guard)
+
       @object = object
       @machine = machine
       @from_name = machine.states.fetch(options[:from]).name
       @to_name = options[:to] && machine.states.fetch(options[:to]).name
       @guard = options[:guard]
       @deep = options[:deep]
-      
-      initial_paths.each {|path| walk(path)}
+
+      initial_paths.each { |path| walk(path) }
     end
-    
+
     # Lists all of the states that can be transitioned from through the paths in
     # this collection.
-    # 
+    #
     # For example,
-    # 
+    #
     #   paths.from_states # => [:parked, :idling, :first_gear, ...]
     def from_states
       flat_map(&:from_states).uniq
     end
-    
+
     # Lists all of the states that can be transitioned to through the paths in
     # this collection.
-    # 
+    #
     # For example,
-    # 
+    #
     #   paths.to_states # => [:idling, :first_gear, :second_gear, ...]
     def to_states
       flat_map(&:to_states).uniq
     end
-    
+
     # Lists all of the events that can be fired through the paths in this
     # collection.
-    # 
+    #
     # For example,
-    # 
+    #
     #   paths.events  # => [:park, :ignite, :shift_up, ...]
     def events
       flat_map(&:events).uniq
     end
-    
-    private
-      # Gets the initial set of paths to walk
-      def initial_paths
-        machine.events.transitions_for(object, :from => from_name, :guard => @guard).map do |transition|
-          path = Path.new(object, machine, :target => to_name, :guard => @guard)
-          path << transition
-          path
-        end
-      end
-      
-      # Walks down the given path.  Each new path that matches the configured
-      # requirements will be added to this collection.
-      def walk(path)
-        self << path if path.complete?
-        path.walk {|next_path| walk(next_path)} unless to_name && path.complete? && !@deep
+
+  private
+
+    # Gets the initial set of paths to walk
+    def initial_paths
+      machine.events.transitions_for(object, from: from_name, guard: @guard).map do |transition|
+        path = Path.new(object, machine, target: to_name, guard: @guard)
+        path << transition
+        path
       end
+    end
+
+    # Walks down the given path.  Each new path that matches the configured
+    # requirements will be added to this collection.
+    def walk(path)
+      self << path if path.complete?
+      path.walk { |next_path| walk(next_path) } unless to_name && path.complete? && !@deep
+    end
   end
 end