ultra-smart-sys 0.0.1

data/state_machines-0.201.0/lib/state_machines/extensions.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+module StateMachines
+  module ClassMethods
+    def self.extended(base) # :nodoc:
+      base.class_eval do
+        @state_machines = MachineCollection.new
+      end
+    end
+
+    # Gets the current list of state machines defined for this class.  This
+    # class-level attribute acts like an inheritable attribute.  The attribute
+    # is available to each subclass, each having a copy of its superclass's
+    # attribute.
+    #
+    # The hash of state machines maps <tt>:attribute</tt> => +machine+, e.g.
+    #
+    #   Vehicle.state_machines # => {:state => #<StateMachines::Machine:0xb6f6e4a4 ...>}
+    def state_machines
+      @state_machines ||= superclass.state_machines.dup
+    end
+  end
+
+  module InstanceMethods
+    # Runs one or more events in parallel.  All events will run through the
+    # following steps:
+    # * Before callbacks
+    # * Persist state
+    # * Invoke action
+    # * After callbacks
+    #
+    # For example, if two events (for state machines A and B) are run in
+    # parallel, the order in which steps are run is:
+    # * A - Before transition callbacks
+    # * B - Before transition callbacks
+    # * A - Persist new state
+    # * B - Persist new state
+    # * A - Invoke action
+    # * B - Invoke action (only if different than A's action)
+    # * A - After transition callbacks
+    # * B - After transition callbacks
+    #
+    # *Note* that multiple events on the same state machine / attribute cannot
+    # be run in parallel.  If this is attempted, an ArgumentError will be
+    # raised.
+    #
+    # == Halting callbacks
+    #
+    # When running multiple events in parallel, special consideration should
+    # be taken with regard to how halting within callbacks affects the flow.
+    #
+    # For *before* callbacks, any <tt>:halt</tt> error that's thrown will
+    # immediately cancel the perform for all transitions.  As a result, it's
+    # possible for one event's transition to affect the continuation of
+    # another.
+    #
+    # On the other hand, any <tt>:halt</tt> error that's thrown within an
+    # *after* callback with only affect that event's transition.  Other
+    # transitions will continue to run their own callbacks.
+    #
+    # == Example
+    #
+    #   class Vehicle
+    #     state_machine :initial => :parked do
+    #       event :ignite do
+    #         transition :parked => :idling
+    #       end
+    #
+    #       event :park do
+    #         transition :idling => :parked
+    #       end
+    #     end
+    #
+    #     state_machine :alarm_state, :namespace => 'alarm', :initial => :on do
+    #       event :enable do
+    #         transition all => :active
+    #       end
+    #
+    #       event :disable do
+    #         transition all => :off
+    #       end
+    #     end
+    #   end
+    #
+    #   vehicle = Vehicle.new                         # => #<Vehicle:0xb7c02850 @state="parked", @alarm_state="active">
+    #   vehicle.state                                 # => "parked"
+    #   vehicle.alarm_state                           # => "active"
+    #
+    #   vehicle.fire_events(:ignite, :disable_alarm)  # => true
+    #   vehicle.state                                 # => "idling"
+    #   vehicle.alarm_state                           # => "off"
+    #
+    #   # If any event fails, the entire event chain fails
+    #   vehicle.fire_events(:ignite, :enable_alarm)   # => false
+    #   vehicle.state                                 # => "idling"
+    #   vehicle.alarm_state                           # => "off"
+    #
+    #   # Exception raised on invalid event
+    #   vehicle.fire_events(:park, :invalid)          # => StateMachines::InvalidEvent: :invalid is an unknown event
+    #   vehicle.state                                 # => "idling"
+    #   vehicle.alarm_state                           # => "off"
+    def fire_events(*events)
+      self.class.state_machines.fire_events(self, *events)
+    end
+
+    # Run one or more events in parallel.  If any event fails to run, then
+    # a StateMachines::InvalidTransition exception will be raised.
+    #
+    # See StateMachines::InstanceMethods#fire_events for more information.
+    #
+    # == Example
+    #
+    #   class Vehicle
+    #     state_machine :initial => :parked do
+    #       event :ignite do
+    #         transition :parked => :idling
+    #       end
+    #
+    #       event :park do
+    #         transition :idling => :parked
+    #       end
+    #     end
+    #
+    #     state_machine :alarm_state, :namespace => 'alarm', :initial => :active do
+    #       event :enable do
+    #         transition all => :active
+    #       end
+    #
+    #       event :disable do
+    #         transition all => :off
+    #       end
+    #     end
+    #   end
+    #
+    #   vehicle = Vehicle.new                         # => #<Vehicle:0xb7c02850 @state="parked", @alarm_state="active">
+    #   vehicle.fire_events(:ignite, :disable_alarm)  # => true
+    #
+    #   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])) || raise(StateMachines::InvalidParallelTransition.new(self, events))
+    end
+
+    protected
+
+    def initialize_state_machines(options = {}, &) # :nodoc:
+      self.class.state_machines.initialize_states(self, options, &)
+    end
+  end
+end

data/state_machines-0.201.0/lib/state_machines/helper_module.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module StateMachines
+  # Represents a type of module that defines instance / class methods for a
+  # state machine
+  class HelperModule < Module # :nodoc:
+    def initialize(machine, kind)
+      @machine = machine
+      @kind = kind
+    end
+
+    # Provides a human-readable description of the module
+    def to_s
+      owner_class = @machine.owner_class
+      owner_class_name = owner_class.name && !owner_class.name.empty? ? owner_class.name : owner_class.to_s
+      "#{owner_class_name} #{@machine.name.inspect} #{@kind} helpers"
+    end
+  end
+end

data/state_machines-0.201.0/lib/state_machines/integrations/base.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module StateMachines
+  module Integrations
+    # Provides a set of base helpers for managing individual integrations
+    module Base
+      module ClassMethods
+        # The default options to use for state machines using this integration
+        attr_reader :defaults
+
+        # The name of the integration
+        def integration_name
+          @integration_name ||= begin
+            name = self.name.split('::').last
+            name.gsub!(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+            name.gsub!(/([a-z\d])([A-Z])/, '\1_\2')
+            name.downcase!
+            name.to_sym
+          end
+        end
+
+        # The list of ancestor names that cause this integration to matched.
+        def matching_ancestors
+          []
+        end
+
+        # Whether the integration should be used for the given class.
+        def matches?(klass)
+          matching_ancestors.any? { |ancestor| klass <= ancestor }
+        end
+
+        # Whether the integration should be used for the given list of ancestors.
+        def matches_ancestors?(ancestors)
+          (ancestors & matching_ancestors).any?
+        end
+
+        # Additional options that this integration adds to the state machine.
+        # Integrations can override this method to specify additional valid options.
+        def integration_options
+          []
+        end
+      end
+
+      def self.included(base) # :nodoc:
+        base.extend ClassMethods
+      end
+    end
+  end
+end

data/state_machines-0.201.0/lib/state_machines/integrations.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module StateMachines
+  # Integrations allow state machines to take advantage of features within the
+  # context of a particular library.  This is currently most useful with
+  # database libraries.  For example, the various database integrations allow
+  # state machines to hook into features like:
+  # * Saving
+  # * Transactions
+  # * Observers
+  # * Scopes
+  # * Callbacks
+  # * Validation errors
+  #
+  # This type of integration allows the user to work with state machines in a
+  # fashion similar to other object models in their application.
+  #
+  # The integration interface is loosely defined by various unimplemented
+  # methods in the StateMachines::Machine class.  See that class or the various
+  # built-in integrations for more information about how to define additional
+  # integrations.
+  module Integrations
+    @integrations = []
+
+    class << self
+      #  Register integration
+      def register(name_or_module)
+        case name_or_module.class.to_s
+        when 'Module'
+          add(name_or_module)
+        else
+          raise IntegrationError
+        end
+        true
+      end
+
+      def reset # :nodoc:#
+        @integrations = []
+      end
+
+      # Gets a list of all of the available integrations for use.
+      #
+      # == Example
+      #
+      #   StateMachines::Integrations.integrations
+      #   # => []
+      #   StateMachines::Integrations.register(StateMachines::Integrations::ActiveModel)
+      #   StateMachines::Integrations.integrations
+      #   # => [StateMachines::Integrations::ActiveModel]
+      attr_reader :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
+      # namespace and find one that successfully matches the class.
+      #
+      # == Examples
+      #
+      #   class Vehicle
+      #   end
+      #
+      #   class ActiveModelVehicle
+      #     include ActiveModel::Observing
+      #     include ActiveModel::Validations
+      #   end
+      #
+      #   class ActiveRecordVehicle < ActiveRecord::Base
+      #   end
+      #
+      #   StateMachines::Integrations.match(Vehicle)             # => nil
+      #   StateMachines::Integrations.match(ActiveModelVehicle)  # => StateMachines::Integrations::ActiveModel
+      #   StateMachines::Integrations.match(ActiveRecordVehicle) # => StateMachines::Integrations::ActiveRecord
+      def match(klass)
+        integrations.detect { |integration| integration.matches?(klass) }
+      end
+
+      # Attempts to find an integration that matches the given list of ancestors.
+      # This will look through all of the built-in integrations under the StateMachines::Integrations
+      # namespace and find one that successfully matches one of the ancestors.
+      #
+      # == Examples
+      #
+      #   StateMachines::Integrations.match_ancestors([])                    # => nil
+      #   StateMachines::Integrations.match_ancestors([ActiveRecord::Base]) # => StateMachines::Integrations::ActiveModel
+      def match_ancestors(ancestors)
+        integrations.detect { |integration| integration.matches_ancestors?(ancestors) }
+      end
+
+      # Finds an integration with the given name.  If the integration cannot be
+      # found, then a NameError exception will be raised.
+      #
+      # == Examples
+      #
+      #   StateMachines::Integrations.find_by_name(:active_model)  # => StateMachines::Integrations::ActiveModel
+      #   StateMachines::Integrations.find_by_name(:active_record) # => StateMachines::Integrations::ActiveRecord
+      #   StateMachines::Integrations.find_by_name(:invalid)       # => StateMachines::IntegrationNotFound: :invalid is an invalid integration
+      def find_by_name(name)
+        integrations.detect { |integration| integration.integration_name == name } || raise(IntegrationNotFound.new(name))
+      end
+
+      private
+
+      def add(integration)
+        return unless integration.respond_to?(:integration_name)
+
+        @integrations.insert(0, integration) unless @integrations.include?(integration)
+      end
+    end
+  end
+end

data/state_machines-0.201.0/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/state_machines-0.201.0/lib/state_machines/machine/async_extensions.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+# This file provides optional async extensions for the Machine class.
+# It should only be loaded when async functionality is explicitly requested.
+
+module StateMachines
+  class Machine
+    # AsyncMode extensions for the Machine class
+    # Provides async-aware methods while maintaining backward compatibility
+    module AsyncExtensions
+      # Instance methods added to Machine for async support
+
+      # Configure this specific machine instance for async mode
+      #
+      # Example:
+      #   class Vehicle
+      #     state_machine initial: :parked do
+      #       configure_async_mode! # Enable async for this machine
+      #
+      #       event :ignite do
+      #         transition parked: :idling
+      #       end
+      #     end
+      #   end
+      def configure_async_mode!(enabled = true)
+        if enabled
+          begin
+            require 'state_machines/async_mode'
+            @async_mode_enabled = true
+
+            owner_class.include(StateMachines::AsyncMode::ThreadSafeState)
+            owner_class.include(StateMachines::AsyncMode::AsyncEvents)
+            extend(StateMachines::AsyncMode::AsyncMachine)
+
+            # Extend events to generate async versions
+            events.each do |event|
+              event.extend(StateMachines::AsyncMode::AsyncEventExtensions)
+            end
+          rescue LoadError => e
+            # Fallback to sync mode with warning (only once per class)
+            unless owner_class.instance_variable_get(:@async_fallback_warned)
+              warn <<~WARNING
+                ⚠️  #{owner_class.name}: Async mode requested but not available on #{RUBY_ENGINE}.
+
+                #{e.message}
+
+                ⚠️  Falling back to synchronous mode. Results may be unpredictable due to engine limitations.
+                For production async support, use MRI Ruby (CRuby) 3.2+
+              WARNING
+              owner_class.instance_variable_set(:@async_fallback_warned, true)
+            end
+
+            @async_mode_enabled = false
+          end
+        else
+          @async_mode_enabled = false
+        end
+
+        self
+      end
+
+      # Check if this specific machine instance has async mode enabled
+      def async_mode_enabled?
+        @async_mode_enabled || false
+      end
+
+      # Thread-safe version of state reading
+      def read_safely(object, attribute, ivar = false)
+        object.read_state_safely(self, attribute, ivar)
+      end
+
+      # Thread-safe version of state writing
+      def write_safely(object, attribute, value, ivar = false)
+        object.write_state_safely(self, attribute, value, ivar)
+      end
+
+      # Thread-safe callback execution for async operations
+      def run_callbacks_safely(type, object, context, transition)
+        object.state_machine_mutex.with_write_lock do
+          callbacks[type].each { |callback| callback.call(object, context, transition) }
+        end
+      end
+    end
+
+    # Include async extensions by default (but only load AsyncMode when requested)
+    include AsyncExtensions
+  end
+end