ultra-smart-sys 0.0.1

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

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module StateMachines
+  class Machine
+    module Parsing
+      private
+
+      # Parses callback arguments for backward compatibility with both positional
+      # and keyword argument styles. Supports Ruby 3.2+ keyword arguments while
+      # maintaining full backward compatibility with the legacy API.
+      def parse_callback_arguments(args, options)
+        # Handle legacy positional args: before_transition(:method1, :method2, from: :state)
+        if args.any?
+          # Extract hash options from the end of args if present
+          parsed_options = args.last.is_a?(Hash) ? args.pop.dup : {}
+
+          # Merge any additional keyword options
+          parsed_options.merge!(options) if options.any?
+
+          # Remaining args become the :do option (method names to call)
+          parsed_options[:do] = args if args.any?
+
+          parsed_options
+        else
+          # Pure keyword argument style: before_transition(from: :state, to: :other, do: :method)
+          options.dup
+        end
+      end
+
+      # Adds a new transition callback of the given type.
+      def add_callback(type, options, &)
+        callbacks[type == :around ? :before : type] << callback = Callback.new(type, options, &)
+        add_states(callback.known_states)
+        callback
+      end
+
+      # Tracks the given set of states in the list of all known states for
+      # this machine
+      def add_states(new_states)
+        new_states.map do |new_state|
+          # Check for other states that use a different class type for their name.
+          # This typically prevents string / symbol misuse.
+          if new_state && (conflict = states.detect { |state| state.name && state.name.class != new_state.class })
+            raise ArgumentError, "#{new_state.inspect} state defined as #{new_state.class}, #{conflict.name.inspect} defined as #{conflict.name.class}; all states must be consistent"
+          end
+
+          unless (state = states[new_state])
+            states << state = State.new(self, new_state)
+
+            # Copy states over to sibling machines
+            sibling_machines.each { |machine| machine.states << state }
+          end
+
+          state
+        end
+      end
+
+      # Tracks the given set of events in the list of all known events for
+      # this machine
+      def add_events(new_events)
+        new_events.map do |new_event|
+          # Check for other states that use a different class type for their name.
+          # This typically prevents string / symbol misuse.
+          if (conflict = events.detect { |event| event.name.class != new_event.class })
+            raise ArgumentError, "#{new_event.inspect} event defined as #{new_event.class}, #{conflict.name.inspect} defined as #{conflict.name.class}; all events must be consistent"
+          end
+
+          unless (event = events[new_event])
+            events << event = Event.new(self, new_event)
+          end
+
+          event
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module StateMachines
+  class Machine
+    module Rendering
+      # Gets the renderer for this machine.
+      def renderer
+        @renderer ||= StdioRenderer.new
+      end
+
+      # Generates a visual representation of this machine for a given format.
+      def draw(**)
+        renderer.draw(self, **)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module StateMachines
+  class Machine
+    module Scoping
+      protected
+
+      # Defines the with/without scope helpers for this attribute.  Both the
+      # singular and plural versions of the attribute are defined for each
+      # scope helper.  A custom plural can be specified if it cannot be
+      # automatically determined by either calling +pluralize+ on the attribute
+      # name or adding an "s" to the end of the name.
+      def define_scopes(custom_plural = nil)
+        plural = custom_plural || pluralize(name)
+
+        %i[with without].each do |kind|
+          [name, plural].map(&:to_s).uniq.each do |suffix|
+            method = "#{kind}_#{suffix}"
+
+            next unless (scope = send("create_#{kind}_scope", method))
+
+            # Converts state names to their corresponding values so that they
+            # can be looked up properly
+            define_helper(:class, method) do |machine, klass, *states|
+              run_scope(scope, machine, klass, states)
+            end
+          end
+        end
+      end
+
+      # Creates a scope for finding objects *with* a particular value or values
+      # for the attribute.
+      #
+      # By default, this is a no-op.
+      def create_with_scope(name); end
+
+      # Creates a scope for finding objects *without* a particular value or
+      # values for the attribute.
+      #
+      # By default, this is a no-op.
+      def create_without_scope(name); end
+    end
+  end
+end

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

@@ -0,0 +1,398 @@
+# frozen_string_literal: true
+
+module StateMachines
+  class Machine
+    module StateMethods
+      # Gets the initial state of the machine for the given object. If a dynamic
+      # initial state was configured for this machine, then the object will be
+      # passed into the lambda block to help determine the actual state.
+      #
+      # == Examples
+      #
+      # With a static initial state:
+      #
+      #   class Vehicle
+      #     state_machine :initial => :parked do
+      #       ...
+      #     end
+      #   end
+      #
+      #   vehicle = Vehicle.new
+      #   Vehicle.state_machine.initial_state(vehicle)  # => #<StateMachines::State name=:parked value="parked" initial=true>
+      #
+      # With a dynamic initial state:
+      #
+      #   class Vehicle
+      #     attr_accessor :force_idle
+      #
+      #     state_machine :initial => lambda {|vehicle| vehicle.force_idle ? :idling : :parked} do
+      #       ...
+      #     end
+      #   end
+      #
+      #   vehicle = Vehicle.new
+      #
+      #   vehicle.force_idle = true
+      #   Vehicle.state_machine.initial_state(vehicle)  # => #<StateMachines::State name=:idling value="idling" initial=false>
+      #
+      #   vehicle.force_idle = false
+      #   Vehicle.state_machine.initial_state(vehicle)  # => #<StateMachines::State name=:parked value="parked" initial=false>
+      def initial_state(object)
+        states.fetch(dynamic_initial_state? ? evaluate_method(object, @initial_state) : @initial_state) if instance_variable_defined?(:@initial_state)
+      end
+
+      # Whether a dynamic initial state is being used in the machine
+      def dynamic_initial_state?
+        instance_variable_defined?(:@initial_state) && @initial_state.is_a?(Proc)
+      end
+
+      # Initializes the state on the given object.  Initial values are only set if
+      # the machine's attribute hasn't been previously initialized.
+      #
+      # Configuration options:
+      # * <tt>:force</tt> - Whether to initialize the state regardless of its
+      #   current value
+      # * <tt>:to</tt> - A hash to set the initial value in instead of writing
+      #   directly to the object
+      def initialize_state(object, options = {})
+        state = initial_state(object)
+        return unless state && (options[:force] || initialize_state?(object))
+
+        value = state.value
+
+        if (hash = options[:to])
+          hash[attribute.to_s] = value
+        else
+          write(object, :state, value)
+        end
+      end
+
+      # Customizes the definition of one or more states in the machine.
+      #
+      # Configuration options:
+      # * <tt>:value</tt> - The actual value to store when an object transitions
+      #   to the state.  Default is the name (stringified).
+      # * <tt>:cache</tt> - If a dynamic value (via a lambda block) is being used,
+      #   then setting this to true will cache the evaluated result
+      # * <tt>:if</tt> - Determines whether an object's value matches the state
+      #   (e.g. :value => lambda {Time.now}, :if => lambda {|state| !state.nil?}).
+      #   By default, the configured value is matched.
+      # * <tt>:human_name</tt> - The human-readable version of this state's name.
+      #   By default, this is either defined by the integration or stringifies the
+      #   name and converts underscores to spaces.
+      #
+      # == Customizing the stored value
+      #
+      # Whenever a state is automatically discovered in the state machine, its
+      # default value is assumed to be the stringified version of the name.  For
+      # example,
+      #
+      #   class Vehicle
+      #     state_machine :initial => :parked do
+      #       event :ignite do
+      #         transition :parked => :idling
+      #       end
+      #     end
+      #   end
+      #
+      # In the above state machine, there are two states automatically discovered:
+      # :parked and :idling.  These states, by default, will store their stringified
+      # equivalents when an object moves into that state (e.g. "parked" / "idling").
+      #
+      # For legacy systems or when tying state machines into existing frameworks,
+      # it's oftentimes necessary to need to store a different value for a state
+      # than the default.  In order to continue taking advantage of an expressive
+      # state machine and helper methods, every defined state can be re-configured
+      # with a custom stored value.  For example,
+      #
+      #   class Vehicle
+      #     state_machine :initial => :parked do
+      #       event :ignite do
+      #         transition :parked => :idling
+      #       end
+      #
+      #       state :idling, :value => 'IDLING'
+      #       state :parked, :value => 'PARKED
+      #     end
+      #   end
+      #
+      # This is also useful if being used in association with a database and,
+      # instead of storing the state name in a column, you want to store the
+      # state's foreign key:
+      #
+      #   class VehicleState < ActiveRecord::Base
+      #   end
+      #
+      #   class Vehicle < ActiveRecord::Base
+      #     state_machine :attribute => :state_id, :initial => :parked do
+      #       event :ignite do
+      #         transition :parked => :idling
+      #       end
+      #
+      #       states.each do |state|
+      #         self.state(state.name, :value => lambda { VehicleState.find_by_name(state.name.to_s).id }, :cache => true)
+      #       end
+      #     end
+      #   end
+      #
+      # In the above example, each known state is configured to store it's
+      # associated database id in the +state_id+ attribute.  Also, notice that a
+      # lambda block is used to define the state's value.  This is required in
+      # situations (like testing) where the model is loaded without any existing
+      # data (i.e. no VehicleState records available).
+      #
+      # One caveat to the above example is to keep performance in mind.  To avoid
+      # constant db hits for looking up the VehicleState ids, the value is cached
+      # by specifying the <tt>:cache</tt> option.  Alternatively, a custom
+      # caching strategy can be used like so:
+      #
+      #   class VehicleState < ActiveRecord::Base
+      #     cattr_accessor :cache_store
+      #     self.cache_store = ActiveSupport::Cache::MemoryStore.new
+      #
+      #     def self.find_by_name(name)
+      #       cache_store.fetch(name) { find(:first, :conditions => {:name => name}) }
+      #     end
+      #   end
+      #
+      # === Dynamic values
+      #
+      # In addition to customizing states with other value types, lambda blocks
+      # can also be specified to allow for a state's value to be determined
+      # dynamically at runtime.  For example,
+      #
+      #   class Vehicle
+      #     state_machine :purchased_at, :initial => :available do
+      #       event :purchase do
+      #         transition all => :purchased
+      #       end
+      #
+      #       event :restock do
+      #         transition all => :available
+      #       end
+      #
+      #       state :available, :value => nil
+      #       state :purchased, :if => lambda {|value| !value.nil?}, :value => lambda {Time.now}
+      #     end
+      #   end
+      #
+      # In the above definition, the <tt>:purchased</tt> state is customized with
+      # both a dynamic value *and* a value matcher.
+      #
+      # When an object transitions to the purchased state, the value's lambda
+      # block will be called.  This will get the current time and store it in the
+      # object's +purchased_at+ attribute.
+      #
+      # *Note* that the custom matcher is very important here.  Since there's no
+      # way for the state machine to figure out an object's state when it's set to
+      # a runtime value, it must be explicitly defined.  If the <tt>:if</tt> option
+      # were not configured for the state, then an ArgumentError exception would
+      # be raised at runtime, indicating that the state machine could not figure
+      # out what the current state of the object was.
+      #
+      # == Behaviors
+      #
+      # Behaviors define a series of methods to mixin with objects when the current
+      # state matches the given one(s).  This allows instance methods to behave
+      # a specific way depending on what the value of the object's state is.
+      #
+      # For example,
+      #
+      #   class Vehicle
+      #     attr_accessor :driver
+      #     attr_accessor :passenger
+      #
+      #     state_machine :initial => :parked do
+      #       event :ignite do
+      #         transition :parked => :idling
+      #       end
+      #
+      #       state :parked do
+      #         def speed
+      #           0
+      #         end
+      #
+      #         def rotate_driver
+      #           driver = self.driver
+      #           self.driver = passenger
+      #           self.passenger = driver
+      #           true
+      #         end
+      #       end
+      #
+      #       state :idling, :first_gear do
+      #         def speed
+      #           20
+      #         end
+      #
+      #         def rotate_driver
+      #           self.state = 'parked'
+      #           rotate_driver
+      #         end
+      #       end
+      #
+      #       other_states :backing_up
+      #     end
+      #   end
+      #
+      # In the above example, there are two dynamic behaviors defined for the
+      # class:
+      # * +speed+
+      # * +rotate_driver+
+      #
+      # Each of these behaviors are instance methods on the Vehicle class.  However,
+      # which method actually gets invoked is based on the current state of the
+      # object.  Using the above class as the example:
+      #
+      #   vehicle = Vehicle.new
+      #   vehicle.driver = 'John'
+      #   vehicle.passenger = 'Jane'
+      #
+      #   # Behaviors in the "parked" state
+      #   vehicle.state             # => "parked"
+      #   vehicle.speed             # => 0
+      #   vehicle.rotate_driver     # => true
+      #   vehicle.driver            # => "Jane"
+      #   vehicle.passenger         # => "John"
+      #
+      #   vehicle.ignite            # => true
+      #
+      #   # Behaviors in the "idling" state
+      #   vehicle.state             # => "idling"
+      #   vehicle.speed             # => 20
+      #   vehicle.rotate_driver     # => true
+      #   vehicle.driver            # => "John"
+      #   vehicle.passenger         # => "Jane"
+      #
+      # As can be seen, both the +speed+ and +rotate_driver+ instance method
+      # implementations changed how they behave based on what the current state
+      # of the vehicle was.
+      #
+      # === Invalid behaviors
+      #
+      # If a specific behavior has not been defined for a state, then a
+      # NoMethodError exception will be raised, indicating that that method would
+      # not normally exist for an object with that state.
+      #
+      # Using the example from before:
+      #
+      #   vehicle = Vehicle.new
+      #   vehicle.state = 'backing_up'
+      #   vehicle.speed               # => NoMethodError: undefined method 'speed' for #<Vehicle:0xb7d296ac> in state "backing_up"
+      #
+      # === Using matchers
+      #
+      # The +all+ / +any+ matchers can be used to easily define behaviors for a
+      # group of states.  Note, however, that you cannot use these matchers to
+      # set configurations for states.  Behaviors using these matchers can be
+      # defined at any point in the state machine and will always get applied to
+      # the proper states.
+      #
+      # For example:
+      #
+      #   state_machine :initial => :parked do
+      #     ...
+      #
+      #     state all - [:parked, :idling, :stalled] do
+      #       validates_presence_of :speed
+      #
+      #       def speed
+      #         gear * 10
+      #       end
+      #     end
+      #   end
+      #
+      # == State-aware class methods
+      #
+      # In addition to defining scopes for instance methods that are state-aware,
+      # the same can be done for certain types of class methods.
+      #
+      # Some libraries have support for class-level methods that only run certain
+      # behaviors based on a conditions hash passed in.  For example:
+      #
+      #   class Vehicle < ActiveRecord::Base
+      #     state_machine do
+      #       ...
+      #       state :first_gear, :second_gear, :third_gear do
+      #         validates_presence_of   :speed
+      #         validates_inclusion_of  :speed, :in => 0..25, :if => :in_school_zone?
+      #       end
+      #     end
+      #   end
+      #
+      # In the above ActiveRecord model, two validations have been defined which
+      # will *only* run when the Vehicle object is in one of the three states:
+      # +first_gear+, +second_gear+, or +third_gear.  Notice, also, that if/unless
+      # conditions can continue to be used.
+      #
+      # This functionality is not library-specific and can work for any class-level
+      # method that is defined like so:
+      #
+      #   def validates_presence_of(attribute, options = {})
+      #     ...
+      #   end
+      #
+      # The minimum requirement is that the last argument in the method be an
+      # options hash which contains at least <tt>:if</tt> condition support.
+      def state(*names, &)
+        options = names.last.is_a?(Hash) ? names.pop : {}
+        StateMachines::OptionsValidator.assert_valid_keys!(options, :value, :cache, :if, :human_name)
+
+        # Store the context so that it can be used for / matched against any state
+        # that gets added
+        @states.context(names, &) if block_given?
+
+        if names.first.is_a?(Matcher)
+          # Add any states referenced in the matcher.  When matchers are used,
+          # states are not allowed to be configured.
+          raise ArgumentError, "Cannot configure states when using matchers (using #{options.inspect})" if options.any?
+
+          states = add_states(names.first.values)
+        else
+          states = add_states(names)
+
+          # Update the configuration for the state(s)
+          states.each do |state|
+            if options.include?(:value)
+              state.value = options[:value]
+              self.states.update(state)
+            end
+
+            state.human_name = options[:human_name] if options.include?(:human_name)
+            state.cache = options[:cache] if options.include?(:cache)
+            state.matcher = options[:if] if options.include?(:if)
+          end
+        end
+
+        states.length == 1 ? states.first : states
+      end
+
+      alias other_states state
+
+      # Gets the current value stored in the given object's attribute.
+      def read(object, attribute, ivar = false)
+        attribute = self.attribute(attribute)
+        if ivar
+          object.instance_variable_defined?(:"@#{attribute}") ? object.instance_variable_get("@#{attribute}") : nil
+        else
+          object.send(attribute)
+        end
+      end
+
+      # Sets a new value in the given object's attribute.
+      def write(object, attribute, value, ivar = false)
+        attribute = self.attribute(attribute)
+        ivar ? object.instance_variable_set(:"@#{attribute}", value) : object.send("#{attribute}=", value)
+      end
+
+      protected
+
+      # Determines if the machine's attribute needs to be initialized.  This
+      # will only be true if the machine's attribute is blank.
+      def initialize_state?(object)
+        value = read(object, :state)
+        (value.nil? || (value.respond_to?(:empty?) && value.empty?)) && !states[value, :value]
+      end
+    end
+  end
+end

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

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module StateMachines
+  class Machine
+    module Utilities
+      protected
+
+      # Looks up other machines that have been defined in the owner class and
+      # are targeting the same attribute as this machine.  When accessing
+      # sibling machines, they will be automatically copied for the current
+      # class if they haven't been already.  This ensures that any configuration
+      # changes made to the sibling machines only affect this class and not any
+      # base class that may have originally defined the machine.
+      def sibling_machines
+        owner_class.state_machines.each_with_object([]) do |(name, machine), machines|
+          machines << (owner_class.state_machine(name) {}) if machine.attribute == attribute && machine != self
+        end
+      end
+
+      # Determines whether there's already a helper method defined within the
+      # given scope.  This is true only if one of the owner's ancestors defines
+      # the method and is further along in the ancestor chain than this
+      # machine's helper module.
+      def owner_class_ancestor_has_method?(scope, method)
+        return false unless owner_class_has_method?(scope, method)
+
+        superclasses = owner_class.ancestors.select { |ancestor| ancestor.is_a?(Class) }[1..]
+
+        if scope == :class
+          current = owner_class.singleton_class
+          superclass = superclasses.first
+        else
+          current = owner_class
+          superclass = owner_class.superclass
+        end
+
+        # Generate the list of modules that *only* occur in the owner class, but
+        # were included *prior* to the helper modules, in addition to the
+        # superclasses
+        ancestors = current.ancestors - superclass.ancestors + superclasses
+        helper_module_index = ancestors.index(@helper_modules[scope])
+        ancestors = helper_module_index ? ancestors[helper_module_index..].reverse : ancestors.reverse
+
+        # Search for for the first ancestor that defined this method
+        ancestors.detect do |ancestor|
+          ancestor = ancestor.singleton_class if scope == :class && ancestor.is_a?(Class)
+          ancestor.method_defined?(method) || ancestor.private_method_defined?(method)
+        end
+      end
+
+      # Determines whether the given method is defined in the owner class or
+      # in a superclass.
+      def owner_class_has_method?(scope, method)
+        target = scope == :class ? owner_class.singleton_class : owner_class
+        target.method_defined?(method) || target.private_method_defined?(method)
+      end
+
+      # Pluralizes the given word using #pluralize (if available) or simply
+      # adding an "s" to the end of the word
+      def pluralize(word)
+        word = word.to_s
+        if word.respond_to?(:pluralize)
+          word.pluralize
+        else
+          "#{word}s"
+        end
+      end
+
+      # Generates the results for the given scope based on one or more states to
+      # filter by
+      def run_scope(scope, machine, klass, states)
+        values = states.flatten.compact.map { |state| machine.states.fetch(state).value }
+        scope.call(klass, values)
+      end
+
+      # Adds sibling machine configurations to the current machine.  This
+      # will add states from other machines that have the same attribute.
+      def add_sibling_machine_configs
+        # Add existing states
+        sibling_machines.each do |machine|
+          machine.states.each { |state| states << state unless states[state.name] }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module StateMachines
+  class Machine
+    module Validation
+      # Frozen constant to avoid repeated array allocations
+      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
+      ].freeze
+
+      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.each do |pattern|
+          raise SecurityError, "Potentially dangerous code detected in eval string: #{method_string.inspect}" if method_string.match?(pattern)
+        end
+
+        # Basic syntax validation (cross-platform)
+        begin
+          SyntaxValidator.validate!(method_string, '(eval)')
+        rescue SyntaxError => e
+          raise ArgumentError, "Invalid Ruby syntax in eval string: #{e.message}"
+        end
+      end
+    end
+  end
+end