ultra-smart-sys 0.0.1

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

@@ -0,0 +1,227 @@
+# frozen_string_literal: true
+
+require_relative 'syntax_validator'
+
+module StateMachines
+  # Provides a set of helper methods for evaluating methods within the context
+  # of an object.
+  module EvalHelpers
+    # Evaluates one of several different types of methods within the context
+    # of the given object.  Methods can be one of the following types:
+    # * Symbol
+    # * Method / Proc
+    # * String
+    #
+    # == Examples
+    #
+    # Below are examples of the various ways that a method can be evaluated
+    # on an object:
+    #
+    #   class Person
+    #     def initialize(name)
+    #       @name = name
+    #     end
+    #
+    #     def name
+    #       @name
+    #     end
+    #   end
+    #
+    #   class PersonCallback
+    #     def self.run(person)
+    #       person.name
+    #     end
+    #   end
+    #
+    #   person = Person.new('John Smith')
+    #
+    #   evaluate_method(person, :name)                            # => "John Smith"
+    #   evaluate_method(person, PersonCallback.method(:run))      # => "John Smith"
+    #   evaluate_method(person, Proc.new {|person| person.name})  # => "John Smith"
+    #   evaluate_method(person, lambda {|person| person.name})    # => "John Smith"
+    #   evaluate_method(person, '@name')                          # => "John Smith"
+    #
+    # == Additional arguments
+    #
+    # Additional arguments can be passed to the methods being evaluated.  If
+    # 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')
+    #
+    #   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
+      in Symbol => sym
+        klass = (class << object; self; end)
+        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 = proc.arity
+        # Handle blocks for Procs
+        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]
+          else
+            # insert the block to the end of the args
+            args << block
+          end
+        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
+        proc.call(*args, **)
+
+      in Method => meth
+        args.unshift(object)
+        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
+        meth.call(*args, **, &block)
+      in String => str
+        # Input validation for string evaluation
+        validate_eval_string(str)
+
+        # Evaluate the string in the object's context
+        if block_given?
+          # TruffleRuby and some other implementations need special handling for blocks
+          # Create a temporary method to evaluate the string with block support
+          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
+        else
+          object.instance_eval(str, __FILE__, __LINE__)
+        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 | Method => callable
+        arity = callable.arity
+
+        # Arity-based decision for backward compatibility using pattern matching
+        case arity
+        in 0
+          callable.call
+        in 1
+          callable.call(object)
+        in -1
+          # Splat parameters: object + all 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
+          callable.call(object, *event_args[0, args_needed])
+        else
+          # Negative arity other than -1 (unlikely but handle gracefully)
+          callable.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
+    # This is a basic safety check - not foolproof security
+    def validate_eval_string(method_string)
+      # Check for obviously dangerous patterns
+      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
+      ]
+
+      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 - but allow yield since it's valid in block context
+      begin
+        test_code = method_string.include?('yield') ? "def dummy_method; #{method_string}; end" : method_string
+        SyntaxValidator.validate!(test_code, '(eval)')
+      rescue SyntaxError => e
+        raise ArgumentError, "Invalid Ruby syntax in eval string: #{e.message}"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,247 @@
+# frozen_string_literal: true
+
+require_relative 'options_validator'
+
+module StateMachines
+  # An event defines an action that transitions an attribute from one state to
+  # another.  The state that an attribute is transitioned to depends on the
+  # branches configured for the event.
+  class Event
+    include MatcherHelpers
+
+    # The state machine for which this event is defined
+    attr_accessor :machine
+
+    # The name of the event
+    attr_reader :name
+
+    # The fully-qualified name of the event, scoped by the machine's namespace
+    attr_reader :qualified_name
+
+    # The human-readable name for the event
+    attr_writer :human_name
+
+    # The list of branches that determine what state this event transitions
+    # objects to when fired
+    attr_reader :branches
+
+    # A list of all of the states known to this event using the configured
+    # branches/transitions as the source
+    attr_reader :known_states
+
+    # Creates a new event within the context of the given machine
+    #
+    # Configuration options:
+    # * <tt>:human_name</tt> - The human-readable version of this event's name
+    def initialize(machine, name, options = nil, human_name: nil, **extra_options) # :nodoc:
+      # Handle both old hash style and new kwargs style for backward compatibility
+      case options
+      in Hash
+        # Old style: initialize(machine, name, {human_name: 'Custom Name'})
+        StateMachines::OptionsValidator.assert_valid_keys!(options, :human_name)
+        human_name = options[:human_name]
+      in nil
+        # New style: initialize(machine, name, human_name: 'Custom Name')
+        StateMachines::OptionsValidator.assert_valid_keys!(extra_options, :human_name) unless extra_options.empty?
+      else
+        # Handle unexpected options
+        raise ArgumentError, "Unexpected positional argument in Event initialize: #{options.inspect}"
+      end
+
+      @machine = machine
+      @name = name
+      @qualified_name = machine.namespace ? :"#{name}_#{machine.namespace}" : name
+      @human_name = human_name || @name.to_s.tr('_', ' ')
+      reset
+
+      # Output a warning if another event has a conflicting qualified name
+      if (conflict = machine.owner_class.state_machines.detect { |_other_name, other_machine| other_machine != @machine && other_machine.events[qualified_name, :qualified_name] })
+        _name, other_machine = conflict
+        warn "Event #{qualified_name.inspect} for #{machine.name.inspect} is already defined in #{other_machine.name.inspect}"
+      else
+        add_actions
+      end
+    end
+
+    # Creates a copy of this event in addition to the list of associated
+    # branches to prevent conflicts across events within a class hierarchy.
+    def initialize_copy(orig) # :nodoc:
+      super
+      @branches = @branches.dup
+      @known_states = @known_states.dup
+    end
+
+    # Transforms the event name into a more human-readable format, such as
+    # "turn on" instead of "turn_on"
+    def human_name(klass = @machine.owner_class)
+      @human_name.is_a?(Proc) ? @human_name.call(self, klass) : @human_name
+    end
+
+    # Evaluates the given block within the context of this event.  This simply
+    # provides a DSL-like syntax for defining transitions.
+    def context(&)
+      instance_eval(&)
+    end
+
+    # Creates a new transition that determines what to change the current state
+    # to when this event fires.
+    #
+    # Since this transition is being defined within an event context, you do
+    # *not* need to specify the <tt>:on</tt> option for the transition.  For
+    # example:
+    #
+    #  state_machine do
+    #    event :ignite do
+    #      transition :parked => :idling, :idling => same, :if => :seatbelt_on? # Transitions to :idling if seatbelt is on
+    #      transition all => :parked, :unless => :seatbelt_on?                  # Transitions to :parked if seatbelt is off
+    #    end
+    #  end
+    #
+    # See StateMachines::Machine#transition for a description of the possible
+    # configurations for defining transitions.
+    def transition(options)
+      raise ArgumentError, 'Must specify as least one transition requirement' if options.empty?
+
+      # Only a certain subset of explicit options are allowed for transition
+      # requirements
+      StateMachines::OptionsValidator.assert_valid_keys!(options, :from, :to, :except_from, :except_to, :if, :unless, :if_state, :unless_state, :if_all_states, :unless_all_states, :if_any_state, :unless_any_state) if (options.keys - %i[from to on except_from except_to except_on if unless if_state unless_state if_all_states unless_all_states if_any_state unless_any_state]).empty?
+
+      branches << branch = Branch.new(options.merge(on: name))
+      @known_states |= branch.known_states
+      branch
+    end
+
+    # Determines whether any transitions can be performed for this event based
+    # on the current state of the given object.
+    #
+    # If the event can't be fired, then this will return false, otherwise true.
+    #
+    # *Note* that this will not take the object context into account.  Although
+    # a transition may be possible based on the state machine definition,
+    # object-specific behaviors (like validations) may prevent it from firing.
+    def can_fire?(object, requirements = {})
+      !transition_for(object, requirements).nil?
+    end
+
+    # Finds and builds the next transition that can be performed on the given
+    # object.  If no transitions can be made, then this will return nil.
+    #
+    # Valid requirement options:
+    # * <tt>:from</tt> - One or more states being transitioned from.  If none
+    #   are specified, then this will be the object's current state.
+    # * <tt>:to</tt> - One or more states being transitioned to.  If none are
+    #   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.
+    #
+    # 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, event_args))
+
+        # Branch allows for the transition to occur
+        from = requirements[:from]
+        to = if match[:to].is_a?(LoopbackMatcher)
+               from
+             else
+               values = requirements.include?(:to) ? [requirements[:to]].flatten : [from] | machine.states.map { |state| state.name }
+
+               match[:to].filter(values).first
+             end
+
+        return Transition.new(object, machine, name, from, to, !custom_from_state)
+      end
+
+      # No transition matched
+      nil
+    end
+
+    # Attempts to perform the next available transition on the given object.
+    # If no transitions can be made, then this will return false, otherwise
+    # true.
+    #
+    # Any additional arguments are passed to the StateMachines::Transition#perform
+    # instance method.
+    def fire(object, *event_args)
+      machine.reset(object)
+
+      if (transition = transition_for(object, {}, *event_args))
+        transition.perform(*event_args)
+      else
+        on_failure(object, *event_args)
+        false
+      end
+    end
+
+    # Marks the object as invalid and runs any failure callbacks associated with
+    # this event.  This should get called anytime this event fails to transition.
+    def on_failure(object, *args)
+      state = machine.states.match!(object)
+      machine.invalidate(object, :state, :invalid_transition, [[:event, human_name(object.class)], [:state, state.human_name(object.class)]])
+
+      transition = Transition.new(object, machine, name, state.name, state.name)
+      transition.args = args if args.any?
+      transition.run_callbacks(before: false)
+    end
+
+    # Resets back to the initial state of the event, with no branches / known
+    # states associated.  This allows you to redefine an event in situations
+    # where you either are re-using an existing state machine implementation
+    # or are subclassing machines.
+    def reset
+      @branches = []
+      @known_states = []
+    end
+
+    def draw(graph, options = {}, io = $stdout)
+      machine.renderer.draw_event(self, graph, options, io)
+    end
+
+    # Generates a nicely formatted description of this event's contents.
+    #
+    # For example,
+    #
+    #   event = StateMachines::Event.new(machine, :park)
+    #   event.transition all - :idling => :parked, :idling => same
+    #   event   # => #<StateMachines::Event name=:park transitions=[all - :idling => :parked, :idling => same]>
+    def inspect
+      transitions = branches.flat_map do |branch|
+        branch.state_requirements.map do |state_requirement|
+          "#{state_requirement[:from].description} => #{state_requirement[:to].description}"
+        end
+      end.join(', ')
+
+      "#<#{self.class} name=#{name.inspect} transitions=[#{transitions}]>"
+    end
+
+    protected
+
+    # Add the various instance methods that can transition the object using
+    # the current event
+    def add_actions
+      # Checks whether the event can be fired on the current object
+      machine.define_helper(:instance, "can_#{qualified_name}?") do |machine, object, *args, **kwargs|
+        machine.event(name).can_fire?(object, *args, **kwargs)
+      end
+
+      # Gets the next transition that would be performed if the event were
+      # fired now
+      machine.define_helper(:instance, "#{qualified_name}_transition") do |machine, object, *args, **kwargs|
+        machine.event(name).transition_for(object, *args, **kwargs)
+      end
+
+      # Fires the event
+      machine.define_helper(:instance, qualified_name) do |machine, object, *args, **kwargs|
+        machine.event(name).fire(object, *args, **kwargs)
+      end
+
+      # Fires the event, raising an exception if it fails
+      machine.define_helper(:instance, "#{qualified_name}!") do |machine, object, *args, **kwargs|
+        object.send(qualified_name, *args, **kwargs) || raise(StateMachines::InvalidTransition.new(object, machine, name))
+      end
+    end
+  end
+end

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

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+module StateMachines
+  # Represents a collection of events in a state machine
+  class EventCollection < NodeCollection
+    def initialize(machine) # :nodoc:
+      super(machine, index: %i[name qualified_name])
+    end
+
+    # Gets the list of events that can be fired on the given object.
+    #
+    # Valid requirement options:
+    # * <tt>:from</tt> - One or more states being transitioned from.  If none
+    #   are specified, then this will be the object's current state.
+    # * <tt>:to</tt> - One or more states being transitioned to.  If none are
+    #   specified, then this will match any to state.
+    # * <tt>:on</tt> - One or more events that fire the transition.  If none
+    #   are specified, then this will match any event.
+    # * <tt>:guard</tt> - Whether to guard transitions with the if/unless
+    #   conditionals defined for each one.  Default is true.
+    #
+    # == Examples
+    #
+    #   class Vehicle
+    #     state_machine :initial => :parked do
+    #       event :park do
+    #         transition :idling => :parked
+    #       end
+    #
+    #       event :ignite do
+    #         transition :parked => :idling
+    #       end
+    #     end
+    #   end
+    #
+    #   events = Vehicle.state_machine(:state).events
+    #
+    #   vehicle = Vehicle.new               # => #<Vehicle:0xb7c464b0 @state="parked">
+    #   events.valid_for(vehicle)           # => [#<StateMachines::Event name=:ignite transitions=[:parked => :idling]>]
+    #
+    #   vehicle.state = 'idling'
+    #   events.valid_for(vehicle)           # => [#<StateMachines::Event name=:park transitions=[:idling => :parked]>]
+    def valid_for(object, requirements = {})
+      match(requirements).select { |event| event.can_fire?(object, requirements) }
+    end
+
+    # Gets the list of transitions that can be run on the given object.
+    #
+    # Valid requirement options:
+    # * <tt>:from</tt> - One or more states being transitioned from.  If none
+    #   are specified, then this will be the object's current state.
+    # * <tt>:to</tt> - One or more states being transitioned to.  If none are
+    #   specified, then this will match any to state.
+    # * <tt>:on</tt> - One or more events that fire the transition.  If none
+    #   are specified, then this will match any event.
+    # * <tt>:guard</tt> - Whether to guard transitions with the if/unless
+    #   conditionals defined for each one.  Default is true.
+    #
+    # == Examples
+    #
+    #   class Vehicle
+    #     state_machine :initial => :parked do
+    #       event :park do
+    #         transition :idling => :parked
+    #       end
+    #
+    #       event :ignite do
+    #         transition :parked => :idling
+    #       end
+    #     end
+    #   end
+    #
+    #   events = Vehicle.state_machine.events
+    #
+    #   vehicle = Vehicle.new                             # => #<Vehicle:0xb7c464b0 @state="parked">
+    #   events.transitions_for(vehicle)                   # => [#<StateMachines::Transition attribute=:state event=:ignite from="parked" from_name=:parked to="idling" to_name=:idling>]
+    #
+    #   vehicle.state = 'idling'
+    #   events.transitions_for(vehicle)                   # => [#<StateMachines::Transition attribute=:state event=:park from="idling" from_name=:idling to="parked" to_name=:parked>]
+    #
+    #   # Search for explicit transitions regardless of the current state
+    #   events.transitions_for(vehicle, :from => :parked) # => [#<StateMachines::Transition attribute=:state event=:ignite from="parked" from_name=:parked to="idling" to_name=:idling>]
+    def transitions_for(object, requirements = {})
+      match(requirements).map { |event| event.transition_for(object, requirements) }.compact
+    end
+
+    # Gets the transition that should be performed for the event stored in the
+    # given object's event attribute.  This also takes an additional parameter
+    # for automatically invalidating the object if the event or transition are
+    # invalid.  By default, this is turned off.
+    #
+    # *Note* that if a transition has already been generated for the event, then
+    # that transition will be used.
+    #
+    # == Examples
+    #
+    #   class Vehicle < ActiveRecord::Base
+    #     state_machine :initial => :parked do
+    #       event :ignite do
+    #         transition :parked => :idling
+    #       end
+    #     end
+    #   end
+    #
+    #   vehicle = Vehicle.new                       # => #<Vehicle id: nil, state: "parked">
+    #   events = Vehicle.state_machine.events
+    #
+    #   vehicle.state_event = nil
+    #   events.attribute_transition_for(vehicle)    # => nil # Event isn't defined
+    #
+    #   vehicle.state_event = 'invalid'
+    #   events.attribute_transition_for(vehicle)    # => false # Event is invalid
+    #
+    #   vehicle.state_event = 'ignite'
+    #   events.attribute_transition_for(vehicle)    # => #<StateMachines::Transition attribute=:state event=:ignite from="parked" from_name=:parked to="idling" to_name=:idling>
+    def attribute_transition_for(object, invalidate = false)
+      return unless machine.action
+
+      # TODO, simplify
+      # First try the regular event_transition
+      transition = machine.read(object, :event_transition)
+
+      # If not found and we have stored transitions by machine (issue #91)
+      if !transition && (transitions_by_machine = object.instance_variable_get(:@_state_machine_event_transitions))
+        transition = transitions_by_machine[machine.name]
+      end
+
+      transition || if event_name = machine.read(object, :event)
+                      if event = self[event_name.to_sym, :name]
+                        event.transition_for(object) || begin
+                          # No valid transition: invalidate
+                          machine.invalidate(object, :event, :invalid_event, [[:state, machine.states.match!(object).human_name(object.class)]]) if invalidate
+                          false
+                        end
+                      else
+                        # Event is unknown: invalidate
+                        machine.invalidate(object, :event, :invalid) if invalidate
+                        false
+                      end
+                    end
+    end
+
+    private
+
+    def match(requirements) # :nodoc:
+      requirements && requirements[:on] ? [fetch(requirements.delete(:on))] : self
+    end
+  end
+end