state_machines 0.101.0 → 0.200.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0b9c5ce3b64a05bfea23f266688b2dd1623124d030e4d4eaaa31d0c8b9c5f28c
-  data.tar.gz: 3126dccbc693deb8b3255408202400360fdffb14e439eda3923f4c3a320f452f
+  metadata.gz: 10897c2b3fdaea1f4728eb063c09f7996c6164f938d814dc486c746c4e91c081
+  data.tar.gz: e7e89af7bfa089d2f1a7c7324f028223e530231e808e34398a2665c11992c168
 SHA512:
-  metadata.gz: d6982ddb9e837d4e7d7763b69045733f2751a74a867fa38789f58e7232a96583f7b2336ed8af7d5ebd0196ae58562aa8f19fb7d2f0f79425a1c5c22e6ddda966
-  data.tar.gz: 315a781c1daa8f85a6b9f20790245191f5540014fb35b1e2a2a41827828ab7748b33de43e016b088da3054f9ef60b541ba390d492d7aad23f95f546b9b9e933d
+  metadata.gz: cb901d7e14ae688dbfec57c312a6edc338156dc0b239a9f56f6898443bbb3ed33e1aad85a260b5ab6c6aa21f3513fdac1e19f24b09418d8994be6f6f80a50a41
+  data.tar.gz: ca11e59b75a28e0c3a9f27fae6a9ac194082a9a1a034d1160050f21c8645f69111e6179e64c5d0048143f5d095f789207372c9d2ef3b3d2a0a07e10cd154438d

data/lib/state_machines/async_mode/async_transition_collection.rb

@@ -31,18 +31,7 @@ module StateMachines
           # Create async tasks for each transition
           tasks = map do |transition|
             Async do
-              if use_event_attributes? && !block_given?
-                transition.transient = true
-                transition.machine.write_safely(object, :event_transition, transition)
-                run_actions
-                transition
-              else
-                within_transaction do
-                  catch(:halt) { run_callbacks(&block) }
-                  rollback unless success?
-                end
-                transition
-              end
+              execute_transition(transition, &block)
             end
           end
 
@@ -80,18 +69,7 @@ module StateMachines
           each do |transition|
             threads << Thread.new do
               begin
-                result = if use_event_attributes? && !block_given?
-                          transition.transient = true
-                          transition.machine.write_safely(object, :event_transition, transition)
-                          run_actions
-                          transition
-                        else
-                          within_transaction do
-                            catch(:halt) { run_callbacks(&block) }
-                            rollback unless success?
-                          end
-                          transition
-                        end
+                result = execute_transition(transition, &block)
 
                 results_mutex.with_write_lock { results << result }
               rescue StandardError => e
@@ -112,6 +90,23 @@ module StateMachines
 
       private
 
+      # Runs a single transition either via event attributes or the standard
+      # callback/transaction flow, returning the transition on completion
+      def execute_transition(transition, &block)
+        if use_event_attributes? && !block_given?
+          transition.transient = true
+          transition.machine.write_safely(object, :event_transition, transition)
+          run_actions
+        else
+          within_transaction do
+            catch(:halt) { run_callbacks(&block) }
+            rollback unless success?
+          end
+        end
+
+        transition
+      end
+
       # Override run_actions to be thread-safe when needed
       def run_actions(&block)
         catch_exceptions do

data/lib/state_machines/eval_helpers.rb

@@ -163,41 +163,25 @@ module StateMachines
         # Symbol methods currently don't support event arguments
         # This maintains backward compatibility
         evaluate_method(object, method)
-      in Proc => proc
-        arity = proc.arity
+      in Proc | Method => callable
+        arity = callable.arity
 
         # Arity-based decision for backward compatibility using pattern matching
         case arity
         in 0
-          proc.call
+          callable.call
         in 1
-          proc.call(object)
+          callable.call(object)
         in -1
           # Splat parameters: object + all event args
-          proc.call(object, *event_args)
+          callable.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])
+          callable.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)
+          callable.call(object, *event_args)
         end
       in String
         # String evaluation doesn't support event arguments for security

data/lib/state_machines/machine/callbacks.rb

@@ -5,46 +5,320 @@ module StateMachines
     module Callbacks
       # Creates a callback that will be invoked *before* a transition is
       # performed so long as the given requirements match the transition.
+      #
+      # == The callback
+      #
+      # Callbacks must be defined as either an argument, in the :do option, or
+      # as a block.  For example,
+      #
+      #   class Vehicle
+      #     state_machine do
+      #       before_transition :set_alarm
+      #       before_transition :set_alarm, all => :parked
+      #       before_transition all => :parked, :do => :set_alarm
+      #       before_transition all => :parked do |vehicle, transition|
+      #         vehicle.set_alarm
+      #       end
+      #       ...
+      #     end
+      #   end
+      #
+      # Notice that the first three callbacks are the same in terms of how the
+      # methods to invoke are defined.  However, using the <tt>:do</tt> can
+      # provide for a more fluid DSL.
+      #
+      # In addition, multiple callbacks can be defined like so:
+      #
+      #   class Vehicle
+      #     state_machine do
+      #       before_transition :set_alarm, :lock_doors, all => :parked
+      #       before_transition all => :parked, :do => [:set_alarm, :lock_doors]
+      #       before_transition :set_alarm do |vehicle, transition|
+      #         vehicle.lock_doors
+      #       end
+      #     end
+      #   end
+      #
+      # Notice that the different ways of configuring methods can be mixed.
+      #
+      # == State requirements
+      #
+      # Callbacks can require that the machine be transitioning from and to
+      # specific states.  These requirements use a Hash syntax to map beginning
+      # states to ending states.  For example,
+      #
+      #   before_transition :parked => :idling, :idling => :first_gear, :do => :set_alarm
+      #
+      # In this case, the +set_alarm+ callback will only be called if the machine
+      # is transitioning from +parked+ to +idling+ or from +idling+ to +parked+.
+      #
+      # To help define state requirements, a set of helpers are available for
+      # slightly more complex matching:
+      # * <tt>all</tt> - Matches every state/event in the machine
+      # * <tt>all - [:parked, :idling, ...]</tt> - Matches every state/event except those specified
+      # * <tt>any</tt> - An alias for +all+ (matches every state/event in the machine)
+      # * <tt>same</tt> - Matches the same state being transitioned from
+      #
+      # See StateMachines::MatcherHelpers for more information.
+      #
+      # Examples:
+      #
+      #   before_transition :parked => [:idling, :first_gear], :do => ...     # Matches from parked to idling or first_gear
+      #   before_transition all - [:parked, :idling] => :idling, :do => ...   # Matches from every state except parked and idling to idling
+      #   before_transition all => :parked, :do => ...                        # Matches all states to parked
+      #   before_transition any => same, :do => ...                           # Matches every loopback
+      #
+      # == Event requirements
+      #
+      # In addition to state requirements, an event requirement can be defined so
+      # that the callback is only invoked on specific events using the +on+
+      # option.  This can also use the same matcher helpers as the state
+      # requirements.
+      #
+      # Examples:
+      #
+      #   before_transition :on => :ignite, :do => ...                        # Matches only on ignite
+      #   before_transition :on => all - :ignite, :do => ...                  # Matches on every event except ignite
+      #   before_transition :parked => :idling, :on => :ignite, :do => ...    # Matches from parked to idling on ignite
+      #
+      # == Verbose Requirements
+      #
+      # Requirements can also be defined using verbose options rather than the
+      # implicit Hash syntax and helper methods described above.
+      #
+      # Configuration options:
+      # * <tt>:from</tt> - One or more states being transitioned from.  If none
+      #   are specified, then all states will match.
+      # * <tt>:to</tt> - One or more states being transitioned to.  If none are
+      #   specified, then all states will match.
+      # * <tt>:on</tt> - One or more events that fired the transition.  If none
+      #   are specified, then all events will match.
+      # * <tt>:except_from</tt> - One or more states *not* being transitioned from
+      # * <tt>:except_to</tt> - One more states *not* being transitioned to
+      # * <tt>:except_on</tt> - One or more events that *did not* fire the transition
+      #
+      # Examples:
+      #
+      #   before_transition :from => :ignite, :to => :idling, :on => :park, :do => ...
+      #   before_transition :except_from => :ignite, :except_to => :idling, :except_on => :park, :do => ...
+      #
+      # == Conditions
+      #
+      # In addition to the state/event requirements, a condition can also be
+      # defined to help determine whether the callback should be invoked.
+      #
+      # Configuration options:
+      # * <tt>:if</tt> - A method, proc or string to call to determine if the
+      #   callback should occur (e.g. :if => :allow_callbacks, or
+      #   :if => lambda {|user| user.signup_step > 2}). The method, proc or string
+      #   should return or evaluate to a true or false value.
+      # * <tt>:unless</tt> - A method, proc or string to call to determine if the
+      #   callback should not occur (e.g. :unless => :skip_callbacks, or
+      #   :unless => lambda {|user| user.signup_step <= 2}). The method, proc or
+      #   string should return or evaluate to a true or false value.
+      #
+      # Examples:
+      #
+      #   before_transition :parked => :idling, :if => :moving?, :do => ...
+      #   before_transition :on => :ignite, :unless => :seatbelt_on?, :do => ...
+      #
+      # == Accessing the transition
+      #
+      # In addition to passing the object being transitioned, the actual
+      # transition describing the context (e.g. event, from, to) can be accessed
+      # as well.  This additional argument is only passed if the callback allows
+      # for it.
+      #
+      # For example,
+      #
+      #   class Vehicle
+      #     # Only specifies one parameter (the object being transitioned)
+      #     before_transition all => :parked do |vehicle|
+      #       vehicle.set_alarm
+      #     end
+      #
+      #     # Specifies 2 parameters (object being transitioned and actual transition)
+      #     before_transition all => :parked do |vehicle, transition|
+      #       vehicle.set_alarm(transition)
+      #     end
+      #   end
+      #
+      # *Note* that the object in the callback will only be passed in as an
+      # argument if callbacks are configured to *not* be bound to the object
+      # involved.  This is the default and may change on a per-integration basis.
+      #
+      # See StateMachines::Transition for more information about the
+      # attributes available on the transition.
+      #
+      # == Usage with delegates
+      #
+      # As noted above, state_machine uses the callback method's argument list
+      # arity to determine whether to include the transition in the method call.
+      # If you're using delegates, such as those defined in ActiveSupport or
+      # Forwardable, the actual arity of the delegated method gets masked.  This
+      # means that callbacks which reference delegates will always get passed the
+      # transition as an argument.  For example:
+      #
+      #   class Vehicle
+      #     extend Forwardable
+      #     delegate :refresh => :dashboard
+      #
+      #     state_machine do
+      #       before_transition :refresh
+      #       ...
+      #     end
+      #
+      #     def dashboard
+      #       @dashboard ||= Dashboard.new
+      #     end
+      #   end
+      #
+      #   class Dashboard
+      #     def refresh(transition)
+      #       # ...
+      #     end
+      #   end
+      #
+      # In the above example, <tt>Dashboard#refresh</tt> *must* defined a
+      # +transition+ argument.  Otherwise, an +ArgumentError+ exception will get
+      # raised.  The only way around this is to avoid the use of delegates and
+      # manually define the delegate method so that the correct arity is used.
+      #
+      # == Examples
+      #
+      # Below is an example of a class with one state machine and various types
+      # of +before+ transitions defined for it:
+      #
+      #   class Vehicle
+      #     state_machine do
+      #       # Before all transitions
+      #       before_transition :update_dashboard
+      #
+      #       # Before specific transition:
+      #       before_transition [:first_gear, :idling] => :parked, :on => :park, :do => :take_off_seatbelt
+      #
+      #       # With conditional callback:
+      #       before_transition all => :parked, :do => :take_off_seatbelt, :if => :seatbelt_on?
+      #
+      #       # Using helpers:
+      #       before_transition all - :stalled => same, :on => any - :crash, :do => :update_dashboard
+      #       ...
+      #     end
+      #   end
+      #
+      # As can be seen, any number of transitions can be created using various
+      # combinations of configuration options.
       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, &)
+        add_transition_callback(:before, args, options, &)
       end
 
       # Creates a callback that will be invoked *after* a transition is
       # performed so long as the given requirements match the transition.
+      #
+      # See +before_transition+ for a description of the possible configurations
+      # for defining callbacks.
       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, &)
+        add_transition_callback(:after, args, options, &)
       end
 
-      # Creates a callback that will be invoked *around* a transition so long
-      # as the given requirements match the transition.
+      # Creates a callback that will be invoked *around* a transition so long as
+      # the given requirements match the transition.
+      #
+      # == The callback
+      #
+      # Around callbacks wrap transitions, executing code both before and after.
+      # These callbacks are defined in the exact same manner as before / after
+      # callbacks with the exception that the transition must be yielded to in
+      # order to finish running it.
+      #
+      # If defining +around+ callbacks using blocks, you must yield within the
+      # transition by directly calling the block (since yielding is not allowed
+      # within blocks).
+      #
+      # For example,
+      #
+      #   class Vehicle
+      #     state_machine do
+      #       around_transition do |block|
+      #         Benchmark.measure { block.call }
+      #       end
+      #
+      #       around_transition do |vehicle, block|
+      #         logger.info "vehicle was #{state}..."
+      #         block.call
+      #         logger.info "...and is now #{state}"
+      #       end
+      #
+      #       around_transition do |vehicle, transition, block|
+      #         logger.info "before #{transition.event}: #{vehicle.state}"
+      #         block.call
+      #         logger.info "after #{transition.event}: #{vehicle.state}"
+      #       end
+      #     end
+      #   end
+      #
+      # Notice that referencing the block is similar to doing so within an
+      # actual method definition in that it is always the last argument.
+      #
+      # On the other hand, if you're defining +around+ callbacks using method
+      # references, you can yield like normal:
+      #
+      #   class Vehicle
+      #     state_machine do
+      #       around_transition :benchmark
+      #       ...
+      #     end
+      #
+      #     def benchmark
+      #       Benchmark.measure { yield }
+      #     end
+      #   end
+      #
+      # See +before_transition+ for a description of the possible configurations
+      # for defining callbacks.
       def around_transition(*args, **options, &)
+        add_transition_callback(:around, args, options, &)
+      end
+
+      # Creates a callback that will be invoked *after* a transition failures to
+      # be performed so long as the given requirements match the transition.
+      #
+      # See +before_transition+ for a description of the possible configurations
+      # for defining callbacks.  *Note* however that you cannot define the state
+      # requirements in these callbacks.  You may only define event requirements.
+      #
+      # = The callback
+      #
+      # Failure callbacks get invoked whenever an event fails to execute.  This
+      # can happen when no transition is available, a +before+ callback halts
+      # execution, or the action associated with this machine fails to succeed.
+      # In any of these cases, any failure callback that matches the attempted
+      # transition will be run.
+      #
+      # For example,
+      #
+      #   class Vehicle
+      #     state_machine do
+      #       after_failure do |vehicle, transition|
+      #         logger.error "vehicle #{vehicle} failed to transition on #{transition.event}"
+      #       end
+      #
+      #       after_failure :on => :ignite, :do => :log_ignition_failure
+      #
+      #       ...
+      #     end
+      #   end
+      def after_failure(*args, **options, &)
         # Extract legacy positional arguments and merge with keyword options
         parsed_options = parse_callback_arguments(args, options)
+        StateMachines::OptionsValidator.assert_valid_keys!(parsed_options, :on, :do, :if, :unless)
 
-        # 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, &)
+        add_callback(:failure, parsed_options, &)
       end
 
-      # Creates a callback that will be invoked after a transition has failed
-      # to be performed.
-      def after_failure(*args, **options, &)
+      private
+
+      def add_transition_callback(type, args, options, &)
         # Extract legacy positional arguments and merge with keyword options
         parsed_options = parse_callback_arguments(args, options)
 
@@ -52,7 +326,7 @@ module StateMachines
         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, &)
+        add_callback(type, parsed_options, &)
       end
     end
   end