state_machines 0.20.0 → 0.31.0

data/lib/state_machines/eval_helpers.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative 'syntax_validator'
+
 module StateMachines
   # Provides a set of helper methods for evaluating methods within the context
   # of an object.
@@ -45,6 +47,11 @@ module StateMachines
     # the method defines additional arguments other than the object context,
     # then all arguments are required.
     #
+    # For guard conditions in state machines, event arguments can be passed
+    # automatically based on the guard's arity:
+    # - Guards with arity 1 receive only the object (backward compatible)
+    # - Guards with arity -1 or > 1 receive object + event arguments
+    #
     # For example,
     #
     #   person = Person.new('John Smith')
@@ -52,64 +59,186 @@ module StateMachines
     #   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)
-    def evaluate_method(object, method, *args, **kwargs, &block)
+    #
+    # With event arguments for guards:
+    #
+    #   # Single parameter guard (backward compatible)
+    #   guard = lambda {|obj| obj.valid? }
+    #   evaluate_method_with_event_args(object, guard, [arg1, arg2])  # => calls guard.call(object)
+    #
+    #   # Multi-parameter guard (receives event args)
+    #   guard = lambda {|obj, *args| obj.valid? && args[0] == :force }
+    #   evaluate_method_with_event_args(object, guard, [:force])      # => calls guard.call(object, :force)
+    def evaluate_method(object, method, *args, **, &block)
       case method
-        when Symbol
-          klass = (class << object; self; end)
-          args = [] if (klass.method_defined?(method) || klass.private_method_defined?(method)) && object.method(method).arity == 0
-          object.send(method, *args, **kwargs, &block)
-        when Proc
-          args.unshift(object)
-          arity = method.arity
-          # Handle blocks for Procs
-          if block_given? && arity != 0
-            if [1, 2].include?(arity)
-              # Force the block to be either the only argument or the 2nd one
-              # after the object (may mean additional arguments get discarded)
-              args = args[0, arity - 1] + [block]
-            else
-              # Tack the block to the end of the args
-              args << block
-            end
+      in Symbol => sym
+        klass = (class << object; self; end)
+        args = [] if (klass.method_defined?(sym) || klass.private_method_defined?(sym)) && object.method(sym).arity.zero?
+        object.send(sym, *args, **, &block)
+      in Proc => proc
+        args.unshift(object)
+        arity = proc.arity
+        # Handle blocks for Procs
+        case [block_given?, arity]
+        in [true, arity] if arity != 0
+          case arity
+          in 1 | 2
+            # Force the block to be either the only argument or the second one
+            # after the object (may mean additional arguments get discarded)
+            args = args[0, arity - 1] + [block]
           else
-            # These method types are only called with 0, 1, or n arguments
-            args = args[0, arity] if [0, 1].include?(arity)
+            # insert the block to the end of the args
+            args << block
           end
+        in [_, 0 | 1]
+          # These method types are only called with 0, 1, or n arguments
+          args = args[0, arity]
+        else
+          # No changes needed for other cases
+        end
 
         # Call the Proc with the arguments
-        method.call(*args, **kwargs)
+        proc.call(*args, **)
 
-        when Method
-          args.unshift(object)
-          arity = method.arity
+      in Method => meth
+        args.unshift(object)
+        arity = meth.arity
 
-          # Methods handle blocks via &block, not as arguments
-          # Only limit arguments if necessary based on arity
-          args = args[0, arity] if [0, 1].include?(arity)
+        # Methods handle blocks via &block, not as arguments
+        # Only limit arguments if necessary based on arity
+        args = args[0, arity] if [0, 1].include?(arity)
 
-          # Call the Method with the arguments and pass the block
-          method.call(*args, **kwargs, &block)
-        when String
-          if block_given?
-            if StateMachines::Transition.pause_supported?
-              eval(method, object.instance_eval { binding }, &block)
-            else
-              # Support for JRuby and Truffle Ruby, which don't support binding blocks
-              eigen = class << object; self; end
-              eigen.class_eval <<-RUBY, __FILE__, __LINE__ + 1
-                  def __temp_eval_method__(*args, &b)
-                    #{method}
-                  end
-                RUBY
-              result = object.__temp_eval_method__(*args, &block)
-              eigen.send(:remove_method, :__temp_eval_method__)
-              result
-            end
-          else
-            eval(method, object.instance_eval { binding })
-          end
+        # Call the Method with the arguments and pass the block
+        meth.call(*args, **, &block)
+      in String => str
+        # Input validation for string evaluation
+        validate_eval_string(str)
+
+        case [block_given?, StateMachines::Transition.pause_supported?]
+        in [true, true]
+          eval(str, object.instance_eval { binding }, &block)
+        in [true, false]
+          # Support for JRuby and Truffle Ruby, which don't support binding blocks
+          # Need to check with @headius, if jruby 10 does now.
+          eigen = class << object; self; end
+          eigen.class_eval <<-RUBY, __FILE__, __LINE__ + 1
+                def __temp_eval_method__(*args, &b)
+                  #{str}
+                end
+          RUBY
+          result = object.__temp_eval_method__(*args, &block)
+          eigen.send(:remove_method, :__temp_eval_method__)
+          result
+        in [false, _]
+          eval(str, object.instance_eval { binding })
+        end
+      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
+    end
+
+    # Evaluates a guard method with support for event arguments passed to transitions.
+    # This method uses arity detection to determine whether to pass event arguments
+    # to the guard, ensuring backward compatibility.
+    #
+    # == Parameters
+    # * object - The object context to evaluate within
+    # * method - The guard method/proc to evaluate
+    # * event_args - Array of arguments passed to the event (optional)
+    #
+    # == Arity-based behavior
+    # * Arity 1: Only passes the object (backward compatible)
+    # * Arity -1 or > 1: Passes object + event arguments
+    #
+    # == Examples
+    #
+    #   # Backward compatible single-parameter guard
+    #   guard = lambda {|obj| obj.valid? }
+    #   evaluate_method_with_event_args(object, guard, [:force])  # => calls guard.call(object)
+    #
+    #   # New multi-parameter guard receiving event args
+    #   guard = lambda {|obj, *args| obj.valid? && args[0] != :skip }
+    #   evaluate_method_with_event_args(object, guard, [:skip])   # => calls guard.call(object, :skip)
+    def evaluate_method_with_event_args(object, method, event_args = [])
+      case method
+      in Symbol
+        # Symbol methods currently don't support event arguments
+        # This maintains backward compatibility
+        evaluate_method(object, method)
+      in Proc => proc
+        arity = proc.arity
+
+        # Arity-based decision for backward compatibility using pattern matching
+        case arity
+        in 0
+          proc.call
+        in 1
+          proc.call(object)
+        in -1
+          # Splat parameters: object + all event args
+          proc.call(object, *event_args)
+        in arity if arity > 1
+          # Explicit parameters: object + limited event args
+          args_needed = arity - 1 # Subtract 1 for the object parameter
+          proc.call(object, *event_args[0, args_needed])
+        else
+          # Negative arity other than -1 (unlikely but handle gracefully)
+          proc.call(object, *event_args)
+        end
+      in Method => meth
+        arity = meth.arity
+
+        case arity
+        in 0
+          meth.call
+        in 1
+          meth.call(object)
+        in -1
+          meth.call(object, *event_args)
+        in arity if arity > 1
+          args_needed = arity - 1
+          meth.call(object, *event_args[0, args_needed])
         else
-          raise ArgumentError, 'Methods must be a symbol denoting the method to call, a block to be invoked, or a string to be evaluated'
+          meth.call(object, *event_args)
+        end
+      in String
+        # String evaluation doesn't support event arguments for security
+        evaluate_method(object, method)
+      else
+        # Fall back to standard evaluation
+        evaluate_method(object, method)
+      end
+    end
+
+    private
+
+    # Validates string input before eval to prevent code injection
+    # This is a basic safety check - not foolproof security
+    def validate_eval_string(method_string)
+      # Check for obviously dangerous patterns
+      dangerous_patterns = [
+        /`.*`/,           # Backticks (shell execution)
+        /system\s*\(/,    # System calls
+        /exec\s*\(/,      # Exec calls
+        /eval\s*\(/,      # Nested eval
+        /require\s+['"]/, # Require statements
+        /load\s+['"]/, # Load statements
+        /File\./,         # File operations
+        /IO\./,           # IO operations
+        /Dir\./,          # Directory operations
+        /Kernel\./        # Kernel operations
+      ]
+
+      dangerous_patterns.each do |pattern|
+        raise SecurityError, "Potentially dangerous code detected in eval string: #{method_string.inspect}" if method_string.match?(pattern)
+      end
+
+      # Basic syntax validation - but allow yield since it's valid in block context
+      begin
+        test_code = method_string.include?('yield') ? "def dummy_method; #{method_string}; end" : method_string
+        SyntaxValidator.validate!(test_code, '(eval)')
+      rescue SyntaxError => e
+        raise ArgumentError, "Invalid Ruby syntax in eval string: #{e.message}"
       end
     end
   end

data/lib/state_machines/event.rb

@@ -7,7 +7,6 @@ module StateMachines
   # another.  The state that an attribute is transitioned to depends on the
   # branches configured for the event.
   class Event
-
     include MatcherHelpers
 
     # The state machine for which this event is defined
@@ -34,7 +33,7 @@ module StateMachines
     #
     # Configuration options:
     # * <tt>:human_name</tt> - The human-readable version of this event's name
-    def initialize(machine, name, options = nil, human_name: nil, **extra_options) #:nodoc:
+    def initialize(machine, name, options = nil, human_name: nil, **extra_options) # :nodoc:
       # Handle both old hash style and new kwargs style for backward compatibility
       if options.is_a?(Hash)
         # Old style: initialize(machine, name, {human_name: 'Custom Name'})
@@ -43,6 +42,7 @@ module StateMachines
       else
         # New style: initialize(machine, name, human_name: 'Custom Name')
         raise ArgumentError, "Unexpected positional argument: #{options.inspect}" unless options.nil?
+
         StateMachines::OptionsValidator.assert_valid_keys!(extra_options, :human_name) unless extra_options.empty?
       end
 
@@ -63,7 +63,7 @@ module StateMachines
 
     # Creates a copy of this event in addition to the list of associated
     # branches to prevent conflicts across events within a class hierarchy.
-    def initialize_copy(orig) #:nodoc:
+    def initialize_copy(orig) # :nodoc:
       super
       @branches = @branches.dup
       @known_states = @known_states.dup
@@ -77,8 +77,8 @@ module StateMachines
 
     # Evaluates the given block within the context of this event.  This simply
     # provides a DSL-like syntax for defining transitions.
-    def context(&block)
-      instance_eval(&block)
+    def context(&)
+      instance_eval(&)
     end
 
     # Creates a new transition that determines what to change the current state
@@ -102,9 +102,7 @@ module StateMachines
 
       # Only a certain subset of explicit options are allowed for transition
       # requirements
-      if (options.keys - [:from, :to, :on, :except_from, :except_to, :except_on, :if, :unless]).empty?
-        StateMachines::OptionsValidator.assert_valid_keys!(options, :from, :to, :except_from, :except_to, :if, :unless)
-      end
+      StateMachines::OptionsValidator.assert_valid_keys!(options, :from, :to, :except_from, :except_to, :if, :unless) if (options.keys - %i[from to on except_from except_to except_on if unless]).empty?
 
       branches << branch = Branch.new(options.merge(on: name))
       @known_states |= branch.known_states
@@ -133,24 +131,26 @@ module StateMachines
     #   specified, then this will match any to state.
     # * <tt>:guard</tt> - Whether to guard transitions with the if/unless
     #   conditionals defined for each one.  Default is true.
-    def transition_for(object, requirements = {})
+    #
+    # Event arguments are passed to guard conditions if they accept multiple parameters.
+    def transition_for(object, requirements = {}, *event_args)
       StateMachines::OptionsValidator.assert_valid_keys!(requirements, :from, :to, :guard)
       requirements[:from] = machine.states.match!(object).name unless (custom_from_state = requirements.include?(:from))
 
       branches.each do |branch|
-        if (match = branch.match(object, requirements))
-          # Branch allows for the transition to occur
-          from = requirements[:from]
-          to = if match[:to].is_a?(LoopbackMatcher)
-                 from
-               else
-                 values = requirements.include?(:to) ? [requirements[:to]].flatten : [from] | machine.states.map { |state| state.name }
-
-                 match[:to].filter(values).first
-               end
-
-          return Transition.new(object, machine, name, from, to, !custom_from_state)
-        end
+        next unless (match = branch.match(object, requirements, event_args))
+
+        # Branch allows for the transition to occur
+        from = requirements[:from]
+        to = if match[:to].is_a?(LoopbackMatcher)
+               from
+             else
+               values = requirements.include?(:to) ? [requirements[:to]].flatten : [from] | machine.states.map { |state| state.name }
+
+               match[:to].filter(values).first
+             end
+
+        return Transition.new(object, machine, name, from, to, !custom_from_state)
       end
 
       # No transition matched
@@ -163,13 +163,13 @@ module StateMachines
     #
     # Any additional arguments are passed to the StateMachines::Transition#perform
     # instance method.
-    def fire(object, *args)
+    def fire(object, *event_args)
       machine.reset(object)
 
-      if (transition = transition_for(object))
-        transition.perform(*args)
+      if (transition = transition_for(object, {}, *event_args))
+        transition.perform(*event_args)
       else
-        on_failure(object, *args)
+        on_failure(object, *event_args)
         false
       end
     end
@@ -194,7 +194,6 @@ module StateMachines
       @known_states = []
     end
 
-
     def draw(graph, options = {}, io = $stdout)
       machine.renderer.draw_event(self, graph, options, io)
     end
@@ -207,16 +206,16 @@ module StateMachines
     #   event.transition all - :idling => :parked, :idling => same
     #   event   # => #<StateMachines::Event name=:park transitions=[all - :idling => :parked, :idling => same]>
     def inspect
-      transitions = branches.map do |branch|
+      transitions = branches.flat_map do |branch|
         branch.state_requirements.map do |state_requirement|
           "#{state_requirement[:from].description} => #{state_requirement[:to].description}"
-        end * ', '
-      end
+        end
+      end.join(', ')
 
-      "#<#{self.class} name=#{name.inspect} transitions=[#{transitions * ', '}]>"
+      "#<#{self.class} name=#{name.inspect} transitions=[#{transitions}]>"
     end
 
-  protected
+    protected
 
     # Add the various instance methods that can transition the object using
     # the current event

data/lib/state_machines/event_collection.rb

@@ -3,8 +3,8 @@
 module StateMachines
   # Represents a collection of events in a state machine
   class EventCollection < NodeCollection
-    def initialize(machine) #:nodoc:
-      super(machine, index: [:name, :qualified_name])
+    def initialize(machine) # :nodoc:
+      super(machine, index: %i[name qualified_name])
     end
 
     # Gets the list of events that can be fired on the given object.
@@ -130,12 +130,11 @@ module StateMachines
                                                      false
                                                    end
                                                  end
-
     end
 
-  private
+    private
 
-    def match(requirements) #:nodoc:
+    def match(requirements) # :nodoc:
       requirements && requirements[:on] ? [fetch(requirements.delete(:on))] : self
     end
   end

data/lib/state_machines/extensions.rb

@@ -2,7 +2,7 @@
 
 module StateMachines
   module ClassMethods
-    def self.extended(base) #:nodoc:
+    def self.extended(base) # :nodoc:
       base.class_eval do
         @state_machines = MachineCollection.new
       end
@@ -138,13 +138,13 @@ module StateMachines
     #   vehicle.fire_events!(:ignite, :disable_alarm) # => StateMachines::InvalidParallelTransition: Cannot run events in parallel: ignite, disable_alarm
     def fire_events!(*events)
       run_action = [true, false].include?(events.last) ? events.pop : true
-      fire_events(*(events + [run_action])) || fail(StateMachines::InvalidParallelTransition.new(self, events))
+      fire_events(*(events + [run_action])) || raise(StateMachines::InvalidParallelTransition.new(self, events))
     end
 
-  protected
+    protected
 
-    def initialize_state_machines(options = {}, &block) #:nodoc:
-      self.class.state_machines.initialize_states(self, options, &block)
+    def initialize_state_machines(options = {}, &) # :nodoc:
+      self.class.state_machines.initialize_states(self, options, &)
     end
   end
 end

data/lib/state_machines/helper_module.rb

@@ -3,7 +3,7 @@
 module StateMachines
   # Represents a type of module that defines instance / class methods for a
   # state machine
-  class HelperModule < Module #:nodoc:
+  class HelperModule < Module # :nodoc:
     def initialize(machine, kind)
       @machine = machine
       @kind = kind

data/lib/state_machines/integrations/base.rb

@@ -35,7 +35,7 @@ module StateMachines
         end
       end
 
-      def self.included(base) #:nodoc:
+      def self.included(base) # :nodoc:
         base.extend ClassMethods
       end
     end

data/lib/state_machines/integrations.rb

@@ -26,15 +26,15 @@ module StateMachines
       #  Register integration
       def register(name_or_module)
         case name_or_module.class.to_s
-          when 'Module'
-            add(name_or_module)
-          else
-            fail IntegrationError
+        when 'Module'
+          add(name_or_module)
+        else
+          raise IntegrationError
         end
         true
       end
 
-      def reset #:nodoc:#
+      def reset # :nodoc:#
         @integrations = []
       end
 
@@ -47,12 +47,9 @@ module StateMachines
       #   StateMachines::Integrations.register(StateMachines::Integrations::ActiveModel)
       #   StateMachines::Integrations.integrations
       #   # => [StateMachines::Integrations::ActiveModel]
-      def integrations
-        # Register all namespaced integrations
-        @integrations
-      end
+      attr_reader :integrations
 
-      alias_method :list, :integrations
+      alias list integrations
 
       # Attempts to find an integration that matches the given class.  This will
       # look through all of the built-in integrations under the StateMachines::Integrations
@@ -102,12 +99,12 @@ module StateMachines
         integrations.detect { |integration| integration.integration_name == name } || raise(IntegrationNotFound.new(name))
       end
 
-    private
+      private
 
       def add(integration)
-        if integration.respond_to?(:integration_name)
-          @integrations.insert(0, integration) unless @integrations.include?(integration)
-        end
+        return unless integration.respond_to?(:integration_name)
+
+        @integrations.insert(0, integration) unless @integrations.include?(integration)
       end
     end
   end

data/lib/state_machines/machine/action_hooks.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module StateMachines
+  class Machine
+    module ActionHooks
+      protected
+
+      # Determines whether action helpers should be defined for this machine.
+      # This is only true if there is an action configured and no other machines
+      # have process this same configuration already.
+      def define_action_helpers?
+        action && owner_class.state_machines.none? { |_name, machine| machine.action == action && machine != self }
+      end
+
+      # Adds helper methods for automatically firing events when an action
+      # is invoked
+      def define_action_helpers
+        return unless action_hook
+
+        @action_hook_defined = true
+        define_action_hook
+      end
+
+      # Hooks directly into actions by defining the same method in an included
+      # module.  As a result, when the action gets invoked, any state events
+      # defined for the object will get run.  Method visibility is preserved.
+      def define_action_hook
+        action_hook = self.action_hook
+        action = self.action
+        private_action_hook = owner_class.private_method_defined?(action_hook)
+
+        # Only define helper if it hasn't
+        define_helper :instance, <<-END_EVAL, __FILE__, __LINE__ + 1
+            def #{action_hook}(*)
+              self.class.state_machines.transitions(self, #{action.inspect}).perform { super }
+            end
+
+            private #{action_hook.inspect} if #{private_action_hook}
+        END_EVAL
+      end
+
+      # The method to hook into for triggering transitions when invoked.  By
+      # default, this is the action configured for the machine.
+      #
+      # Since the default hook technique relies on module inheritance, the
+      # action must be defined in an ancestor of the owner classs in order for
+      # it to be the action hook.
+      def action_hook
+        action && owner_class_ancestor_has_method?(:instance, action) ? action : nil
+      end
+    end
+  end
+end

data/lib/state_machines/machine/callbacks.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module StateMachines
+  class Machine
+    module Callbacks
+      # Creates a callback that will be invoked *before* a transition is
+      # performed so long as the given requirements match the transition.
+      def before_transition(*args, **options, &)
+        # Extract legacy positional arguments and merge with keyword options
+        parsed_options = parse_callback_arguments(args, options)
+
+        # Only validate callback-specific options, not state transition requirements
+        callback_options = parsed_options.slice(:do, :if, :unless, :bind_to_object, :terminator)
+        StateMachines::OptionsValidator.assert_valid_keys!(callback_options, :do, :if, :unless, :bind_to_object, :terminator)
+
+        add_callback(:before, parsed_options, &)
+      end
+
+      # Creates a callback that will be invoked *after* a transition is
+      # performed so long as the given requirements match the transition.
+      def after_transition(*args, **options, &)
+        # Extract legacy positional arguments and merge with keyword options
+        parsed_options = parse_callback_arguments(args, options)
+
+        # Only validate callback-specific options, not state transition requirements
+        callback_options = parsed_options.slice(:do, :if, :unless, :bind_to_object, :terminator)
+        StateMachines::OptionsValidator.assert_valid_keys!(callback_options, :do, :if, :unless, :bind_to_object, :terminator)
+
+        add_callback(:after, parsed_options, &)
+      end
+
+      # Creates a callback that will be invoked *around* a transition so long
+      # as the given requirements match the transition.
+      def around_transition(*args, **options, &)
+        # Extract legacy positional arguments and merge with keyword options
+        parsed_options = parse_callback_arguments(args, options)
+
+        # Only validate callback-specific options, not state transition requirements
+        callback_options = parsed_options.slice(:do, :if, :unless, :bind_to_object, :terminator)
+        StateMachines::OptionsValidator.assert_valid_keys!(callback_options, :do, :if, :unless, :bind_to_object, :terminator)
+
+        add_callback(:around, parsed_options, &)
+      end
+
+      # Creates a callback that will be invoked after a transition has failed
+      # to be performed.
+      def after_failure(*args, **options, &)
+        # Extract legacy positional arguments and merge with keyword options
+        parsed_options = parse_callback_arguments(args, options)
+
+        # Only validate callback-specific options, not state transition requirements
+        callback_options = parsed_options.slice(:do, :if, :unless, :bind_to_object, :terminator)
+        StateMachines::OptionsValidator.assert_valid_keys!(callback_options, :do, :if, :unless, :bind_to_object, :terminator)
+
+        add_callback(:failure, parsed_options, &)
+      end
+    end
+  end
+end