state_machines 0.30.0 → 0.31.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5c732f34387da18f4dc1c3d78cad1fbb111cc88d06d9fe3edcda912adc5e655a
-  data.tar.gz: ef0079a89a1b0e4ddea45dd4a79e11de12740d4eb0c2aa98ad95b5ca7ae3eab8
+  metadata.gz: fcd04394640ccea1429d2e121a46e2c705f8c16b2987b142858ad2f151c9c287
+  data.tar.gz: 58cfb25ff972b1b2802730d9084d3c3b27c59a82e694646ce676e38fc661cbb9
 SHA512:
-  metadata.gz: d71a5bd20b0de0b19e4684b4251954d0cf648e5454b57af96555372bbdee59a9ac855bb27d182e018f87ffa0525b5cd3daff5c3ce53c483f3dec4954d076a331
-  data.tar.gz: 179e0cb6c2a31d14c4078820d254ce35e26d9b5aaa2646e4766b842127411cf49e5ad697d0a764ba79a0036bce5dc288ef113b8bef57c3cac64de8816a23f49b
+  metadata.gz: c9328eea4f9d8d9e57124571de54bb8f5160a044ef913d3e515bcaac933b7355ccf987c10699c71e94145f44bc1e2387342f350dcbff0100d76a5c1c06645321
+  data.tar.gz: 07c7bfad14f7ce103eec5d6dfa48a9117bc0a73cb5433447c4bf7b6cdea1b87b894a12ad6b85b5a0cb05d63dd68e291f980eeca40e60754c13d5b5c44a7fcf29

data/README.md

@@ -1,4 +1,5 @@
 ![Build Status](https://github.com/state-machines/state_machines/actions/workflows/ruby.yml/badge.svg)
+
 # State Machines
 
 State Machines adds support for creating state machines for attributes on any Ruby class.
@@ -9,15 +10,21 @@ State Machines adds support for creating state machines for attributes on any Ru
 
 Add this line to your application's Gemfile:
 
-    gem 'state_machines'
+```ruby
+gem 'state_machines'
+```
 
 And then execute:
 
-    $ bundle
+```sh
+bundle
+```
 
 Or install it yourself as:
 
-    $ gem install state_machines
+```sh
+gem install state_machines
+```
 
 ## Usage
 
@@ -38,7 +45,7 @@ Class definition:
 
 ```ruby
 class Vehicle
-  attr_accessor :seatbelt_on, :time_used, :auto_shop_busy
+  attr_accessor :seatbelt_on, :time_used, :auto_shop_busy, :parking_meter_number
 
   state_machine :state, initial: :parked do
     before_transition parked: any - :parked, do: :put_on_seatbelt
@@ -61,6 +68,18 @@ class Vehicle
       transition [:idling, :first_gear] => :parked
     end
 
+    before_transition on: :park do |vehicle, transition|
+      # If using Rails:
+      # options = transition.args.extract_options!
+
+      options = transition.args.last.is_a?(Hash) ? transition.args.pop : {}
+      meter_number = options[:meter_number]
+
+      unless meter_number.nil?
+        vehicle.parking_meter_number = meter_number
+      end
+    end
+
     event :ignite do
       transition stalled: same, parked: :idling
     end
@@ -130,6 +149,7 @@ class Vehicle
     @seatbelt_on = false
     @time_used = 0
     @auto_shop_busy = true
+    @parking_meter_number = nil
     super() # NOTE: This *must* be called, otherwise states won't get initialized
   end
 
@@ -200,6 +220,11 @@ vehicle.park!                   # => StateMachines:InvalidTransition: Cannot tra
 vehicle.state?(:parked)         # => false
 vehicle.state?(:invalid)        # => IndexError: :invalid is an invalid name
 
+# Transition callbacks can receive arguments
+vehicle.park(meter_number: '12345') # => true
+vehicle.parked?                     # => true
+vehicle.parking_meter_number        # => "12345"
+
 # Namespaced machines have uniquely-generated methods
 vehicle.alarm_state             # => 1
 vehicle.alarm_state_name        # => :active
@@ -790,7 +815,7 @@ For RSpec testing, use the custom RSpec matchers:
 
 ## Contributing
 
-1. Fork it ( https://github.com/state-machines/state_machines/fork )
+1. Fork it ( <https://github.com/state-machines/state_machines/fork> )
 2. Create your feature branch (`git checkout -b my-new-feature`)
 3. Commit your changes (`git commit -am 'Add some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)

data/lib/state_machines/branch.rb

@@ -108,16 +108,18 @@ module StateMachines
     # * <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 = {})
+    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)
+      return unless (match = match_query(query)) && matches_conditions?(object, query, event_args)
 
       match
     end
@@ -178,11 +180,23 @@ module StateMachines
     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) })
+    # given object. Event arguments are passed to guards that accept multiple parameters.
+    def matches_conditions?(object, query, event_args = [])
+      case [query[:guard], if_condition, unless_condition]
+      in [false, _, _]
+        true
+      in [_, nil, nil]
+        true
+      in [_, if_conds, nil] if if_conds
+        Array(if_conds).all? { |condition| evaluate_method_with_event_args(object, condition, event_args) }
+      in [_, nil, unless_conds] if unless_conds
+        Array(unless_conds).none? { |condition| evaluate_method_with_event_args(object, condition, event_args) }
+      in [_, if_conds, unless_conds] if if_conds || unless_conds
+        Array(if_conds).all? { |condition| evaluate_method_with_event_args(object, condition, event_args) } &&
+          Array(unless_conds).none? { |condition| evaluate_method_with_event_args(object, condition, event_args) }
+      else
+        true
+      end
     end
   end
 end

data/lib/state_machines/callback.rb

@@ -193,7 +193,7 @@ module StateMachines
       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

data/lib/state_machines/eval_helpers.rb

@@ -47,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')
@@ -54,18 +59,30 @@ 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)
+    #
+    # 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
+      in Symbol => sym
         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, **, &block)
-      when Proc
+        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 = method.arity
+        arity = proc.arity
         # Handle blocks for Procs
-        if block_given? && arity != 0
-          if [1, 2].include?(arity)
+        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]
@@ -73,52 +90,126 @@ module StateMachines
             # insert the block to the end of the args
             args << block
           end
-        elsif [0, 1].include?(arity)
+        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, **)
+        proc.call(*args, **)
 
-      when Method
+      in Method => meth
         args.unshift(object)
-        arity = method.arity
+        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)
 
         # Call the Method with the arguments and pass the block
-        method.call(*args, **, &block)
-      when String
+        meth.call(*args, **, &block)
+      in String => str
         # Input validation for string evaluation
-        validate_eval_string(method)
+        validate_eval_string(str)
 
-        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
-            # 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)
-                    #{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 })
+        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
+          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

data/lib/state_machines/event.rb

@@ -131,12 +131,14 @@ 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|
-        next unless (match = branch.match(object, requirements))
+        next unless (match = branch.match(object, requirements, event_args))
 
         # Branch allows for the transition to occur
         from = requirements[:from]
@@ -161,13 +163,13 @@ module StateMachines
     #
     # Any additional arguments are passed to the StateMachines::Transition#perform
     # instance method.
-    def fire(object, *)
+    def fire(object, *event_args)
       machine.reset(object)
 
-      if (transition = transition_for(object))
-        transition.perform(*)
+      if (transition = transition_for(object, {}, *event_args))
+        transition.perform(*event_args)
       else
-        on_failure(object, *)
+        on_failure(object, *event_args)
         false
       end
     end
@@ -204,13 +206,13 @@ 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

data/lib/state_machines/machine.rb

@@ -558,8 +558,8 @@ module StateMachines
         else
           name = self.name
           helper_module.class_eval do
-            define_method(method) do |*block_args, **block_kwargs|
-              block.call((scope == :instance ? self.class : self).state_machine(name), self, *block_args, **block_kwargs)
+            define_method(method) do |*args, **kwargs|
+              block.call((scope == :instance ? self.class : self).state_machine(name), self, *args, **kwargs)
             end
           end
         end

data/lib/state_machines/state.rb

@@ -289,9 +289,9 @@ module StateMachines
       predicate_method = "#{qualified_name}?"
 
       if machine.send(:owner_class_ancestor_has_method?, :instance, predicate_method)
-        warn "Instance method #{predicate_method.inspect} is already defined in #{machine.owner_class.ancestors.first.inspect}, use generic helper instead or set StateMachines::Machine.ignore_method_conflicts = true."
+        warn_about_method_conflict(predicate_method, machine.owner_class.ancestors.first)
       elsif machine.send(:owner_class_has_method?, :instance, predicate_method)
-        warn "Instance method #{predicate_method.inspect} is already defined in #{machine.owner_class.inspect}, use generic helper instead or set StateMachines::Machine.ignore_method_conflicts = true."
+        warn_about_method_conflict(predicate_method, machine.owner_class)
       else
         machine.define_helper(:instance, predicate_method) do |machine, object|
           machine.states.matches?(object, name)
@@ -303,5 +303,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/transition.rb

@@ -153,12 +153,21 @@ module StateMachines
     #
     #   vehicle = Vehicle.new
     #   transition = StateMachines::Transition.new(vehicle, machine, :ignite, :parked, :idling)
-    #   transition.perform                  # => Runs the +save+ action after setting the state attribute
-    #   transition.perform(false)           # => Only sets the state attribute
-    #   transition.perform(Time.now)        # => Passes in additional arguments and runs the +save+ action
-    #   transition.perform(Time.now, false) # => Passes in additional arguments and only sets the state attribute
+    #   transition.perform                              # => Runs the +save+ action after setting the state attribute
+    #   transition.perform(false)                       # => Only sets the state attribute
+    #   transition.perform(run_action: false)           # => Only sets the state attribute
+    #   transition.perform(Time.now)                    # => Passes in additional arguments and runs the +save+ action
+    #   transition.perform(Time.now, false)             # => Passes in additional arguments and only sets the state attribute
+    #   transition.perform(Time.now, run_action: false) # => Passes in additional arguments and only sets the state attribute
     def perform(*args)
-      run_action = [true, false].include?(args.last) ? args.pop : true
+      run_action = true
+
+      if [true, false].include?(args.last)
+        run_action = args.pop
+      elsif args.last.is_a?(Hash) && args.last.key?(:run_action)
+        run_action = args.last.delete(:run_action)
+      end
+
       self.args = args
 
       # Run the transition

data/lib/state_machines/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module StateMachines
-  VERSION = '0.30.0'
+  VERSION = '0.31.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: state_machines
 version: !ruby/object:Gem::Version
-  version: 0.30.0
+  version: 0.31.0
 platform: ruby
 authors:
 - Abdelkader Boudih