ultra-smart-sys 0.0.1

data/state_machines-0.201.0/lib/state_machines/machine/callbacks.rb

@@ -0,0 +1,333 @@
+# 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.
+      #
+      # == 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, &)
+        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, &)
+        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.
+      #
+      # == 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)
+
+        add_callback(:failure, parsed_options, &)
+      end
+
+      private
+
+      def add_transition_callback(type, 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(type, parsed_options, &)
+      end
+    end
+  end
+end

data/state_machines-0.201.0/lib/state_machines/machine/class_methods.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module StateMachines
+  class Machine
+    module ClassMethods
+      # Attempts to find or create a state machine for the given class.  For
+      # example,
+      #
+      #   StateMachines::Machine.find_or_create(Vehicle)
+      #   StateMachines::Machine.find_or_create(Vehicle, :initial => :parked)
+      #   StateMachines::Machine.find_or_create(Vehicle, :status)
+      #   StateMachines::Machine.find_or_create(Vehicle, :status, :initial => :parked)
+      #
+      # If a machine of the given name already exists in one of the class's
+      # superclasses, then a copy of that machine will be created and stored
+      # in the new owner class (the original will remain unchanged).
+      def find_or_create(owner_class, *args, &)
+        options = args.last.is_a?(Hash) ? args.pop : {}
+        name = args.first || :state
+
+        # Find an existing machine
+        machine = (owner_class.respond_to?(:state_machines) &&
+                  ((args.first && owner_class.state_machines[name]) || (!args.first &&
+                  owner_class.state_machines.values.first))) || nil
+
+        if machine
+          # Only create a new copy if changes are being made to the machine in
+          # a subclass
+          if machine.owner_class != owner_class && (options.any? || block_given?)
+            machine = machine.clone
+            machine.initial_state = options[:initial] if options.include?(:initial)
+            machine.owner_class = owner_class
+            # Configure async mode if requested in options
+            machine.configure_async_mode!(options[:async]) if options.include?(:async)
+          end
+
+          # Evaluate DSL
+          machine.instance_eval(&) if block_given?
+        else
+          # No existing machine: create a new one
+          machine = new(owner_class, name, options, &)
+        end
+
+        machine
+      end
+
+      def draw(*)
+        raise NotImplementedError
+      end
+
+      # Default messages to use for validation errors in ORM integrations
+      # Thread-safe access via atomic operations on simple values
+      attr_accessor :ignore_method_conflicts
+
+      def default_messages
+        @default_messages ||= {
+          invalid: 'is invalid',
+          invalid_event: 'cannot transition when %s',
+          invalid_transition: 'cannot transition via "%1$s"'
+        }.freeze
+      end
+
+      def default_messages=(messages)
+        # Atomic replacement with frozen object
+        @default_messages = deep_freeze_hash(messages)
+      end
+
+      def replace_messages(message_hash)
+        # Atomic replacement: read current messages, merge with new ones, replace atomically
+        current_messages = @default_messages || {}
+        merged_messages = current_messages.merge(message_hash)
+        @default_messages = deep_freeze_hash(merged_messages)
+      end
+
+      attr_writer :renderer
+
+      def renderer
+        return @renderer if @renderer
+
+        STDIORenderer
+      end
+
+      private
+
+      # Deep freezes a hash and all its string values for thread safety
+      def deep_freeze_hash(hash)
+        hash.each_with_object({}) do |(key, value), frozen_hash|
+          frozen_key = key.respond_to?(:freeze) ? key.freeze : key
+          frozen_value = value.respond_to?(:freeze) ? value.freeze : value
+          frozen_hash[frozen_key] = frozen_value
+        end.freeze
+      end
+    end
+  end
+end

data/state_machines-0.201.0/lib/state_machines/machine/configuration.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module StateMachines
+  class Machine
+    module Configuration
+      # Initializes a new state machine with the given configuration.
+      def initialize(owner_class, *args, &)
+        options = args.last.is_a?(Hash) ? args.pop : {}
+        
+        # Find an integration that matches this machine's owner class
+        @integration = if options.include?(:integration)
+                         options[:integration] && StateMachines::Integrations.find_by_name(options[:integration])
+                       else
+                         StateMachines::Integrations.match(owner_class)
+                       end
+        
+        # Validate options including integration-specific options
+        valid_keys = [:attribute, :initial, :initialize, :action, :plural, :namespace, :integration, :messages, :use_transactions, :async]
+        valid_keys += @integration.integration_options if @integration
+        StateMachines::OptionsValidator.assert_valid_keys!(options, valid_keys)
+
+        if @integration
+          extend @integration
+          options = (@integration.defaults || {}).merge(options)
+        end
+
+        # Add machine-wide defaults
+        options = { use_transactions: true, initialize: true }.merge(options)
+
+        # Set machine configuration
+        @name = args.first || :state
+        @attribute = options[:attribute] || @name
+        @events = EventCollection.new(self)
+        @states = StateCollection.new(self)
+        @callbacks = { before: [], after: [], failure: [] }
+        @namespace = options[:namespace]
+        @messages = options[:messages] || {}
+        @action = options[:action]
+        @use_transactions = options[:use_transactions]
+        @initialize_state = options[:initialize]
+        @action_hook_defined = false
+        @async_requested = options[:async]
+
+        self.owner_class = owner_class
+
+        # Merge with sibling machine configurations
+        add_sibling_machine_configs
+
+        # Define class integration
+        define_helpers
+        define_scopes(options[:plural])
+        after_initialize
+
+        # Evaluate DSL
+        instance_eval(&) if block_given?
+
+        # Configure async mode if requested, after owner_class is set and DSL is evaluated
+        configure_async_mode!(true) if @async_requested
+
+        self.initial_state = options[:initial] unless sibling_machines.any?
+      end
+
+      # Creates a copy of this machine in addition to copies of each associated
+      # event/states/callback, so that the modifications to those collections do
+      # not affect the original machine.
+      def initialize_copy(orig) # :nodoc:
+        super
+
+        @events = @events.dup
+        @events.machine = self
+        @states = @states.dup
+        @states.machine = self
+        @callbacks = { before: @callbacks[:before].dup, after: @callbacks[:after].dup, failure: @callbacks[:failure].dup }
+        @async_requested = orig.instance_variable_get(:@async_requested)
+        @async_mode_enabled = orig.instance_variable_get(:@async_mode_enabled)
+      end
+
+      # Sets the class which is the owner of this state machine.  Any methods
+      # generated by states, events, or other parts of the machine will be defined
+      # on the given owner class.
+      def owner_class=(klass)
+        @owner_class = klass
+
+        # Create modules for extending the class with state/event-specific methods
+        @helper_modules = helper_modules = { instance: HelperModule.new(self, :instance), class: HelperModule.new(self, :class) }
+        owner_class.class_eval do
+          extend helper_modules[:class]
+          include helper_modules[:instance]
+        end
+
+        # Add class-/instance-level methods to the owner class for state initialization
+        unless owner_class < StateMachines::InstanceMethods
+          owner_class.class_eval do
+            extend StateMachines::ClassMethods
+            include StateMachines::InstanceMethods
+          end
+
+          define_state_initializer if @initialize_state
+        end
+
+        # Record this machine as matched to the name in the current owner class.
+        # This will override any machines mapped to the same name in any superclasses.
+        owner_class.state_machines[name] = self
+      end
+
+      # Sets the initial state of the machine.  This can be either the static name
+      # of a state or a lambda block which determines the initial state at
+      # creation time.
+      def initial_state=(new_initial_state)
+        @initial_state = new_initial_state
+        add_states([@initial_state]) unless dynamic_initial_state?
+
+        # Update all states to reflect the new initial state
+        states.each { |state| state.initial = (state.name == @initial_state) }
+
+        # Warn if the owner class and the machine have conflicting defaults for
+        # the machine's attribute. May be deferred by integrations (e.g.
+        # ActiveRecord) to avoid touching the DB at class load time.
+        schedule_conflicting_attribute_default_check
+      end
+
+      # Gets the attribute name for the given machine scope.
+      def attribute(name = :state)
+        name == :state ? @attribute : :"#{self.name}_#{name}"
+      end
+    end
+  end
+end