state_machines 0.5.0 → 0.50.0

data/lib/state_machines/path_collection.rb

@@ -1,23 +1,25 @@
+# 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 +27,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
+
+    # 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

data/lib/state_machines/state.rb

@@ -1,3 +1,7 @@
+# frozen_string_literal: true
+
+require_relative 'options_validator'
+
 module StateMachines
   # A state defines a value that an attribute can be in after being transitioned
   # 0 or more times.  States can represent a value of any type in Ruby, though
@@ -8,7 +12,6 @@ module StateMachines
   # StateMachines::Machine#state for more information about how state-driven
   # behavior can be utilized.
   class State
-
     # The state machine for which this state is defined
     attr_reader :machine
 
@@ -31,7 +34,7 @@ module StateMachines
 
     # Whether or not this state is the initial state to use for new objects
     attr_accessor :initial
-    alias_method :initial?, :initial
+    alias initial? initial
 
     # A custom lambda block for determining whether a given value matches this
     # state
@@ -50,38 +53,59 @@ module StateMachines
     #   (e.g. :value => lambda {Time.now}, :if => lambda {|state| !state.nil?}).
     #   By default, the configured value is matched.
     # * <tt>:human_name</tt> - The human-readable version of this state's name
-    def initialize(machine, name, options = {}) #:nodoc:
-      options.assert_valid_keys(:initial, :value, :cache, :if, :human_name)
+    def initialize(machine, name, options = nil, initial: false, value: :__not_provided__, cache: nil, if: nil, human_name: nil, **extra_options) # :nodoc:
+      # Handle both old hash style and new kwargs style for backward compatibility
+      case options
+      in Hash
+        # Old style: initialize(machine, name, {initial: true, value: 'foo'})
+        StateMachines::OptionsValidator.assert_valid_keys!(options, :initial, :value, :cache, :if, :human_name)
+        initial = options.fetch(:initial, false)
+        value = options.include?(:value) ? options[:value] : :__not_provided__
+        cache = options[:cache]
+        if_condition = options[:if]
+        human_name = options[:human_name]
+      in nil
+        # New style: initialize(machine, name, initial: true, value: 'foo')
+        StateMachines::OptionsValidator.assert_valid_keys!(extra_options, :initial, :value, :cache, :if, :human_name) unless extra_options.empty?
+        if_condition = binding.local_variable_get(:if) # 'if' is a keyword, need special handling
+      else
+        # Handle unexpected options
+        raise ArgumentError, "Unexpected positional argument in State initialize: #{options.inspect}"
+      end
 
       @machine = machine
       @name = name
       @qualified_name = name && machine.namespace ? :"#{machine.namespace}_#{name}" : name
-      @human_name = options[:human_name] || (@name ? @name.to_s.tr('_', ' ') : 'nil')
-      @value = options.include?(:value) ? options[:value] : name && name.to_s
-      @cache = options[:cache]
-      @matcher = options[:if]
-      @initial = options[:initial] == true
+      @human_name = human_name || (@name ? @name.to_s.tr('_', ' ') : 'nil')
+      @value = value == :__not_provided__ ? name&.to_s : value
+      @cache = cache
+      @matcher = if_condition
+      @initial = initial == true
       @context = StateContext.new(self)
 
-      if name
-        conflicting_machines = machine.owner_class.state_machines.select { |other_name, other_machine| other_machine != machine && other_machine.states[qualified_name, :qualified_name] }
-
-        # Output a warning if another machine has a conflicting qualified name
-        # for a different attribute
-        if conflict = conflicting_machines.detect { |other_name, other_machine| other_machine.attribute != machine.attribute }
-          name, other_machine = conflict
-          warn "State #{qualified_name.inspect} for #{machine.name.inspect} is already defined in #{other_machine.name.inspect}"
-        elsif conflicting_machines.empty?
-          # Only bother adding predicates when another machine for the same
-          # attribute hasn't already done so
-          add_predicate
-        end
+      return unless name
+
+      conflicting_machines = machine.owner_class.state_machines.select do |_other_name, other_machine|
+        other_machine != machine && other_machine.states[qualified_name, :qualified_name]
+      end
+
+      # Output a warning if another machine has a conflicting qualified name
+      # for a different attribute
+      if (conflict = conflicting_machines.detect do |_other_name, other_machine|
+        other_machine.attribute != machine.attribute
+      end)
+        _name, other_machine = conflict
+        warn "State #{qualified_name.inspect} for #{machine.name.inspect} is already defined in #{other_machine.name.inspect}"
+      elsif conflicting_machines.empty?
+        # Only bother adding predicates when another machine for the same
+        # attribute hasn't already done so
+        add_predicate
       end
     end
 
     # Creates a copy of this state, excluding the context to prevent conflicts
     # across different machines.
-    def initialize_copy(orig) #:nodoc:
+    def initialize_copy(orig) # :nodoc:
       super
       @context = StateContext.new(self)
     end
@@ -96,10 +120,10 @@ module StateMachines
     # Any objects in a final state will remain so forever given the current
     # machine's definition.
     def final?
-      !machine.events.any? do |event|
+      machine.events.none? do |event|
         event.branches.any? do |branch|
           branch.state_requirements.any? do |requirement|
-            requirement[:from].matches?(name) && !requirement[:to].matches?(name, :from => name)
+            requirement[:from].matches?(name) && !requirement[:to].matches?(name, from: name)
           end
         end
       end
@@ -126,7 +150,7 @@ module StateMachines
     #   description or just the internal name
     def description(options = {})
       label = options[:human_name] ? human_name : name
-      description = label ? label.to_s : label.inspect
+      description = +(label ? label.to_s : label.inspect)
       description << " (#{@value.is_a?(Proc) ? '*' : @value.inspect})" unless name.to_s == @value.to_s
       description
     end
@@ -178,27 +202,27 @@ module StateMachines
     #
     # This can be called multiple times.  Each time a new context is created,
     # a new module will be included in the owner class.
-    def context(&block)
+    def context(&)
       # Include the context
       context = @context
       machine.owner_class.class_eval { include context }
 
       # Evaluate the method definitions and track which ones were added
       old_methods = context_methods
-      context.class_eval(&block)
-      new_methods = context_methods.to_a.select { |(name, method)| old_methods[name] != method }
+      context.class_eval(&)
+      new_methods = context_methods.to_a.reject { |(name, method)| old_methods[name] == method }
 
       # Alias new methods so that the only execute when the object is in this state
       new_methods.each do |(method_name, _method)|
         context_name = context_name_for(method_name)
-        context.class_eval <<-end_eval, __FILE__, __LINE__ + 1
+        context.class_eval <<-END_EVAL, __FILE__, __LINE__ + 1
           alias_method :"#{context_name}", :#{method_name}
           def #{method_name}(*args, &block)
             state = self.class.state_machine(#{machine.name.inspect}).states.fetch(#{name.inspect})
             options = {:method_missing => lambda {super(*args, &block)}, :method_name => #{method_name.inspect}}
             state.call(self, :"#{context_name}", *(args + [options]), &block)
           end
-        end_eval
+        END_EVAL
       end
 
       true
@@ -216,31 +240,30 @@ module StateMachines
     #
     # If the method has never been defined for this state, then a NoMethodError
     # will be raised.
-    def call(object, method, *args, &block)
+    def call(object, method, *args, &)
       options = args.last.is_a?(Hash) ? args.pop : {}
-      options = {:method_name => method}.merge(options)
+      options = { method_name: method }.merge(options)
       state = machine.states.match!(object)
 
       if state == self && object.respond_to?(method)
-        object.send(method, *args, &block)
-      elsif method_missing = options[:method_missing]
+        object.send(method, *args, &)
+      elsif (method_missing = options[:method_missing])
         # Dispatch to the superclass since the object either isn't in this state
         # or this state doesn't handle the method
         begin
           method_missing.call
-        rescue NoMethodError => ex
-          if ex.name.to_s == options[:method_name].to_s && ex.args == args
-            # No valid context for this method
-            raise InvalidContext.new(object, "State #{state.name.inspect} for #{machine.name.inspect} is not a valid context for calling ##{options[:method_name]}")
-          else
-            raise
-          end
+        rescue NoMethodError => e
+          raise unless e.name.to_s == options[:method_name].to_s && e.args == args
+
+          # No valid context for this method
+          raise InvalidContext.new(object,
+                                   "State #{state.name.inspect} for #{machine.name.inspect} is not a valid context for calling ##{options[:method_name]}")
         end
       end
     end
 
-    def draw(graph, options = {})
-      fail NotImplementedError
+    def draw(graph, options = {}, io = $stdout)
+      machine.renderer.draw_state(self, graph, options, io)
     end
 
     # Generates a nicely formatted description of this state's contents.
@@ -255,6 +278,7 @@ module StateMachines
     end
 
     private
+
     # Should the value be cached after it's evaluated for the first time?
     def cache_value?
       @cache
@@ -263,9 +287,16 @@ module StateMachines
     # Adds a predicate method to the owner class so long as a name has
     # actually been configured for the state
     def add_predicate
-      # Checks whether the current value matches this state
-      machine.define_helper(:instance, "#{qualified_name}?") do |machine, object|
-        machine.states.matches?(object, name)
+      predicate_method = "#{qualified_name}?"
+
+      if machine.send(:owner_class_ancestor_has_method?, :instance, predicate_method)
+        warn_about_method_conflict(predicate_method, machine.owner_class.ancestors.first)
+      elsif machine.send(:owner_class_has_method?, :instance, predicate_method)
+        warn_about_method_conflict(predicate_method, machine.owner_class)
+      else
+        machine.define_helper(:instance, predicate_method) do |machine, object|
+          machine.states.matches?(object, name)
+        end
       end
     end
 
@@ -273,5 +304,11 @@ module StateMachines
     def context_name_for(method)
       :"__#{machine.name}_#{name}_#{method}_#{@context.object_id}__"
     end
+
+    def warn_about_method_conflict(method, defined_in)
+      return if StateMachines::Machine.ignore_method_conflicts
+
+      warn "Instance method #{method.inspect} is already defined in #{defined_in.inspect}, use generic helper instead or set StateMachines::Machine.ignore_method_conflicts = true."
+    end
   end
 end

data/lib/state_machines/state_collection.rb

@@ -1,26 +1,28 @@
+# frozen_string_literal: true
+
 module StateMachines
   # Represents a collection of states in a state machine
   class StateCollection < NodeCollection
-    def initialize(machine) #:nodoc:
-      super(machine, :index => [:name, :qualified_name, :value])
+    def initialize(machine) # :nodoc:
+      super(machine, index: %i[name qualified_name value])
     end
 
     # Determines whether the given object is in a specific state.  If the
     # object's current value doesn't match the state, then this will return
     # false, otherwise true.  If the given state is unknown, then an IndexError
     # will be raised.
-    # 
+    #
     # == Examples
-    # 
+    #
     #   class Vehicle
     #     state_machine :initial => :parked do
     #       other_states :idling
     #     end
     #   end
-    #   
+    #
     #   states = Vehicle.state_machine.states
     #   vehicle = Vehicle.new               # => #<Vehicle:0xb7c464b0 @state="parked">
-    #   
+    #
     #   states.matches?(vehicle, :parked)   # => true
     #   states.matches?(vehicle, :idling)   # => false
     #   states.matches?(vehicle, :invalid)  # => IndexError: :invalid is an invalid key for :name index
@@ -31,23 +33,23 @@ module StateMachines
     # Determines the current state of the given object as configured by this
     # state machine.  This will attempt to find a known state that matches
     # the value of the attribute on the object.
-    # 
+    #
     # == Examples
-    # 
+    #
     #   class Vehicle
     #     state_machine :initial => :parked do
     #       other_states :idling
     #     end
     #   end
-    #   
+    #
     #   states = Vehicle.state_machine.states
-    #   
+    #
     #   vehicle = Vehicle.new         # => #<Vehicle:0xb7c464b0 @state="parked">
     #   states.match(vehicle)         # => #<StateMachines::State name=:parked value="parked" initial=true>
-    #   
+    #
     #   vehicle.state = 'idling'
     #   states.match(vehicle)         # => #<StateMachines::State name=:idling value="idling" initial=true>
-    #   
+    #
     #   vehicle.state = 'invalid'
     #   states.match(vehicle)         # => nil
     def match(object)
@@ -58,20 +60,20 @@ module StateMachines
     # Determines the current state of the given object as configured by this
     # state machine.  If no state is found, then an ArgumentError will be
     # raised.
-    # 
+    #
     # == Examples
-    # 
+    #
     #   class Vehicle
     #     state_machine :initial => :parked do
     #       other_states :idling
     #     end
     #   end
-    #   
+    #
     #   states = Vehicle.state_machine.states
-    #   
+    #
     #   vehicle = Vehicle.new         # => #<Vehicle:0xb7c464b0 @state="parked">
     #   states.match!(vehicle)        # => #<StateMachines::State name=:parked value="parked" initial=true>
-    #   
+    #
     #   vehicle.state = 'invalid'
     #   states.match!(vehicle)        # => ArgumentError: "invalid" is not a known state value
     def match!(object)
@@ -80,13 +82,13 @@ module StateMachines
 
     # Gets the order in which states should be displayed based on where they
     # were first referenced.  This will order states in the following priority:
-    # 
+    #
     # 1. Initial state
     # 2. Event transitions (:from, :except_from, :to, :except_to options)
     # 3. States with behaviors
     # 4. States referenced via +state+ or +other_states+
     # 5. States referenced in callbacks
-    # 
+    #
     # This order will determine how the GraphViz visualizations are rendered.
     def by_priority
       order = select { |state| state.initial }.map { |state| state.name }
@@ -102,6 +104,7 @@ module StateMachines
     end
 
     private
+
     # Gets the value for the given attribute on the node
     def value(node, attribute)
       attribute == :value ? node.value(false) : super

data/lib/state_machines/state_context.rb

@@ -1,133 +1,134 @@
-module StateMachines
+# frozen_string_literal: true
+
+require_relative 'options_validator'
 
-  
+module StateMachines
   # Represents a module which will get evaluated within the context of a state.
-  # 
+  #
   # Class-level methods are proxied to the owner class, injecting a custom
   # <tt>:if</tt> condition along with method.  This assumes that the method has
   # support for a set of configuration options, including <tt>:if</tt>.  This
   # condition will check that the object's state matches this context's state.
-  # 
+  #
   # Instance-level methods are used to define state-driven behavior on the
   # state's owner class.
-  # 
+  #
   # == Examples
-  # 
+  #
   #   class Vehicle
   #     class << self
   #       attr_accessor :validations
-  #       
+  #
   #       def validate(options, &block)
   #         validations << options
   #       end
   #     end
-  #     
+  #
   #     self.validations = []
   #     attr_accessor :state, :simulate
-  #     
+  #
   #     def moving?
   #       self.class.validations.all? {|validation| validation[:if].call(self)}
   #     end
   #   end
-  # 
+  #
   # In the above class, a simple set of validation behaviors have been defined.
   # Each validation consists of a configuration like so:
-  # 
+  #
   #   Vehicle.validate :unless => :simulate
   #   Vehicle.validate :if => lambda {|vehicle| ...}
-  # 
+  #
   # In order to scope validations to a particular state context, the class-level
   # +validate+ method can be invoked like so:
-  # 
+  #
   #   machine = StateMachines::Machine.new(Vehicle)
   #   context = StateMachines::StateContext.new(machine.state(:first_gear))
   #   context.validate(:unless => :simulate)
-  #   
+  #
   #   vehicle = Vehicle.new     # => #<Vehicle:0xb7ce491c @simulate=nil, @state=nil>
   #   vehicle.moving?           # => false
-  #   
+  #
   #   vehicle.state = 'first_gear'
   #   vehicle.moving?           # => true
-  #   
+  #
   #   vehicle.simulate = true
   #   vehicle.moving?           # => false
   class StateContext < Module
-
     include EvalHelpers
-    
+
     # The state machine for which this context's state is defined
     attr_reader :machine
-    
+
     # The state that must be present in an object for this context to be active
     attr_reader :state
-    
+
     # Creates a new context for the given state
     def initialize(state)
       @state = state
       @machine = state.machine
-      
+
       state_name = state.name
       machine_name = machine.name
-      @condition = lambda {|object| object.class.state_machine(machine_name).states.matches?(object, state_name)}
+      @condition = ->(object) { object.class.state_machine(machine_name).states.matches?(object, state_name) }
     end
-    
+
     # Creates a new transition that determines what to change the current state
     # to when an event fires from this state.
-    # 
+    #
     # Since this transition is being defined within a state context, you do
     # *not* need to specify the <tt>:from</tt> option for the transition.  For
     # example:
-    # 
+    #
     #   state_machine do
     #     state :parked do
     #       transition :to => :idling, :on => [:ignite, :shift_up]                          # Transitions to :idling
     #       transition :from => [:idling, :parked], :on => :park, :unless => :seatbelt_on?  # Transitions to :parked if seatbelt is off
     #     end
     #   end
-    # 
+    #
     # See StateMachines::Machine#transition for a description of the possible
     # configurations for defining transitions.
     def transition(options)
-      options.assert_valid_keys(:from, :to, :on, :if, :unless)
+      StateMachines::OptionsValidator.assert_valid_keys!(options, :from, :to, :on, :if, :unless)
       raise ArgumentError, 'Must specify :on event' unless options[:on]
       raise ArgumentError, 'Must specify either :to or :from state' unless !options[:to] ^ !options[:from]
-      
-      machine.transition(options.merge(options[:to] ? {:from => state.name} : {:to => state.name}))
+
+      machine.transition(options.merge(options[:to] ? { from: state.name } : { to: state.name }))
     end
-    
+
     # Hooks in condition-merging to methods that don't exist in this module
-    def method_missing(*args, &block)
+    def method_missing(*args, &)
       # Get the configuration
       if args.last.is_a?(Hash)
         options = args.last
       else
         args << options = {}
       end
-      
+
       # Get any existing condition that may need to be merged
       if_condition = options.delete(:if)
       unless_condition = options.delete(:unless)
-      
+
       # Provide scope access to configuration in case the block is evaluated
       # within the object instance
       proxy = self
       proxy_condition = @condition
-      
+
       # Replace the configuration condition with the one configured for this
       # proxy, merging together any existing conditions
       options[:if] = lambda do |*condition_args|
         # Block may be executed within the context of the actual object, so
         # it'll either be the first argument or the executing context
         object = condition_args.first || self
-        
+
         proxy.evaluate_method(object, proxy_condition) &&
-        Array(if_condition).all? {|condition| proxy.evaluate_method(object, condition)} &&
-        !Array(unless_condition).any? {|condition| proxy.evaluate_method(object, condition)}
+          Array(if_condition).all? { |condition| proxy.evaluate_method(object, condition) } &&
+          !Array(unless_condition).any? { |condition| proxy.evaluate_method(object, condition) }
       end
-      
+
       # Evaluate the method on the owner class with the condition proxied
       # through
-      machine.owner_class.send(*args, &block)
+      machine.owner_class.send(*args, &)
     end
   end
 end