ultra-smart-sys 0.0.1

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

@@ -0,0 +1,246 @@
+# frozen_string_literal: true
+
+require_relative 'options_validator'
+
+module StateMachines
+  # Represents a set of requirements that must be met in order for a transition
+  # or callback to occur.  Branches verify that the event, from state, and to
+  # state of the transition match, in addition to if/unless conditionals for
+  # an object's state.
+  class Branch
+    include EvalHelpers
+
+    # The condition that must be met on an object
+    attr_reader :if_condition
+
+    # The condition that must *not* be met on an object
+    attr_reader :unless_condition
+
+    # The requirement for verifying the event being matched
+    attr_reader :event_requirement
+
+    # One or more requirements for verifying the states being matched.  All
+    # requirements contain a mapping of {:from => matcher, :to => matcher}.
+    attr_reader :state_requirements
+
+    # A list of all of the states known to this branch.  This will pull states
+    # from the following options (in the same order):
+    # * +from+ / +except_from+
+    # * +to+ / +except_to+
+    attr_reader :known_states
+
+    # Creates a new branch
+    def initialize(options = {}) # :nodoc:
+      # Build conditionals
+      @if_condition = options.delete(:if)
+      @unless_condition = options.delete(:unless)
+      @if_state_condition = options.delete(:if_state)
+      @unless_state_condition = options.delete(:unless_state)
+      @if_all_states_condition = options.delete(:if_all_states)
+      @unless_all_states_condition = options.delete(:unless_all_states)
+      @if_any_state_condition = options.delete(:if_any_state)
+      @unless_any_state_condition = options.delete(:unless_any_state)
+
+      # Build event requirement
+      @event_requirement = build_matcher(options, :on, :except_on)
+
+      if (options.keys - %i[from to on except_from except_to except_on]).empty?
+        # Explicit from/to requirements specified
+        @state_requirements = [{ from: build_matcher(options, :from, :except_from), to: build_matcher(options, :to, :except_to) }]
+      else
+        # Separate out the event requirement
+        options.delete(:on)
+        options.delete(:except_on)
+
+        # Implicit from/to requirements specified
+        @state_requirements = options.collect do |from, to|
+          from = WhitelistMatcher.new(from) unless from.is_a?(Matcher)
+          to = WhitelistMatcher.new(to) unless to.is_a?(Matcher)
+          { from: from, to: to }
+        end
+      end
+
+      # Track known states.  The order that requirements are iterated is based
+      # on the priority in which tracked states should be added.
+      @known_states = []
+      @state_requirements.each do |state_requirement|
+        %i[from to].each { |option| @known_states |= state_requirement[option].values }
+      end
+    end
+
+    # Determines whether the given object / query matches the requirements
+    # configured for this branch.  In addition to matching the event, from state,
+    # and to state, this will also check whether the configured :if/:unless
+    # conditions pass on the given object.
+    #
+    # == Examples
+    #
+    #   branch = StateMachines::Branch.new(:parked => :idling, :on => :ignite)
+    #
+    #   # Successful
+    #   branch.matches?(object, :on => :ignite)                                   # => true
+    #   branch.matches?(object, :from => nil)                                     # => true
+    #   branch.matches?(object, :from => :parked)                                 # => true
+    #   branch.matches?(object, :to => :idling)                                   # => true
+    #   branch.matches?(object, :from => :parked, :to => :idling)                 # => true
+    #   branch.matches?(object, :on => :ignite, :from => :parked, :to => :idling) # => true
+    #
+    #   # Unsuccessful
+    #   branch.matches?(object, :on => :park)                                     # => false
+    #   branch.matches?(object, :from => :idling)                                 # => false
+    #   branch.matches?(object, :to => :first_gear)                               # => false
+    #   branch.matches?(object, :from => :parked, :to => :first_gear)             # => false
+    #   branch.matches?(object, :on => :park, :from => :parked, :to => :idling)   # => false
+    def matches?(object, query = {})
+      !match(object, query).nil?
+    end
+    
+    # Alias for Minitest's assert_match
+    alias =~ matches?
+
+    # Attempts to match the given object / query against the set of requirements
+    # configured for this branch.  In addition to matching the event, from state,
+    # and to state, this will also check whether the configured :if/:unless
+    # conditions pass on the given object.
+    #
+    # If a match is found, then the event/state requirements that the query
+    # passed successfully will be returned.  Otherwise, nil is returned if there
+    # was no match.
+    #
+    # Query options:
+    # * <tt>:from</tt> - One or more states being transitioned from.  If none
+    #   are specified, then this will always match.
+    # * <tt>:to</tt> - One or more states being transitioned to.  If none are
+    #   specified, then this will always match.
+    # * <tt>:on</tt> - One or more events that fired the transition.  If none
+    #   are specified, then this will always match.
+    # * <tt>:guard</tt> - Whether to guard matches with the if/unless
+    #   conditionals defined for this branch.  Default is true.
+    #
+    # Event arguments are passed to guard conditions if they accept multiple parameters.
+    #
+    # == Examples
+    #
+    #   branch = StateMachines::Branch.new(:parked => :idling, :on => :ignite)
+    #
+    #   branch.match(object, :on => :ignite)  # => {:to => ..., :from => ..., :on => ...}
+    #   branch.match(object, :on => :park)    # => nil
+    def match(object, query = {}, event_args = [])
+      StateMachines::OptionsValidator.assert_valid_keys!(query, :from, :to, :on, :guard)
+
+      return unless (match = match_query(query)) && matches_conditions?(object, query, event_args)
+
+      match
+    end
+
+    def draw(graph, event, valid_states, io = $stdout)
+      machine.renderer.draw_branch(self, graph, event, valid_states, io)
+    end
+
+    protected
+
+    # Builds a matcher strategy to use for the given options.  If neither a
+    # whitelist nor a blacklist option is specified, then an AllMatcher is
+    # built.
+    def build_matcher(options, whitelist_option, blacklist_option)
+      StateMachines::OptionsValidator.assert_exclusive_keys!(options, whitelist_option, blacklist_option)
+
+      if options.include?(whitelist_option)
+        value = options[whitelist_option]
+        value.is_a?(Matcher) ? value : WhitelistMatcher.new(options[whitelist_option])
+      elsif options.include?(blacklist_option)
+        value = options[blacklist_option]
+        raise ArgumentError, ":#{blacklist_option} option cannot use matchers; use :#{whitelist_option} instead" if value.is_a?(Matcher)
+
+        BlacklistMatcher.new(value)
+      else
+        AllMatcher.instance
+      end
+    end
+
+    # Verifies that all configured requirements (event and state) match the
+    # given query.  If a match is found, then a hash containing the
+    # event/state requirements that passed will be returned; otherwise, nil.
+    def match_query(query)
+      query ||= {}
+
+      if match_event(query) && (state_requirement = match_states(query))
+        state_requirement.merge(on: event_requirement)
+      end
+    end
+
+    # Verifies that the event requirement matches the given query
+    def match_event(query)
+      matches_requirement?(query, :on, event_requirement)
+    end
+
+    # Verifies that the state requirements match the given query.  If a
+    # matching requirement is found, then it is returned.
+    def match_states(query)
+      state_requirements.detect do |state_requirement|
+        %i[from to].all? { |option| matches_requirement?(query, option, state_requirement[option]) }
+      end
+    end
+
+    # Verifies that an option in the given query matches the values required
+    # for that option
+    def matches_requirement?(query, option, requirement)
+      !query.include?(option) || requirement.matches?(query[option], query)
+    end
+
+    # Verifies that the conditionals for this branch evaluate to true for the
+    # given object. Event arguments are passed to guards that accept multiple parameters.
+    def matches_conditions?(object, query, event_args = [])
+      return true if query[:guard] == false
+
+      # Evaluate original if/unless conditions
+      if_passes = !if_condition || Array(if_condition).all? { |condition| evaluate_method_with_event_args(object, condition, event_args) }
+      unless_passes = !unless_condition || Array(unless_condition).none? { |condition| evaluate_method_with_event_args(object, condition, event_args) }
+
+      return false unless if_passes && unless_passes
+
+      # Consolidate all state guards
+      state_guards = {
+        if_state: @if_state_condition,
+        unless_state: @unless_state_condition,
+        if_all_states: @if_all_states_condition,
+        unless_all_states: @unless_all_states_condition,
+        if_any_state: @if_any_state_condition,
+        unless_any_state: @unless_any_state_condition
+      }.compact
+
+      return true if state_guards.empty?
+
+      validate_and_check_state_guards(object, state_guards)
+    end
+
+    private
+
+    def validate_and_check_state_guards(object, guards)
+      guards.all? do |guard_type, conditions|
+        case guard_type
+        when :if_state, :if_all_states
+          conditions.all? { |machine, state| check_state(object, machine, state) }
+        when :unless_state
+          conditions.none? { |machine, state| check_state(object, machine, state) }
+        when :if_any_state
+          conditions.any? { |machine, state| check_state(object, machine, state) }
+        when :unless_all_states
+          !conditions.all? { |machine, state| check_state(object, machine, state) }
+        when :unless_any_state
+          conditions.none? { |machine, state| check_state(object, machine, state) }
+        end
+      end
+    end
+
+    def check_state(object, machine_name, state_name)
+      machine = object.class.state_machines[machine_name]
+      raise ArgumentError, "State machine '#{machine_name}' is not defined for #{object.class.name}" unless machine
+
+      state = machine.states[state_name]
+      raise ArgumentError, "State '#{state_name}' is not defined in state machine '#{machine_name}'" unless state
+
+      state.matches?(object.send(machine_name))
+    end
+  end
+end

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

@@ -0,0 +1,223 @@
+# frozen_string_literal: true
+
+require 'state_machines/branch'
+require 'state_machines/eval_helpers'
+
+module StateMachines
+  # Callbacks represent hooks into objects that allow logic to be triggered
+  # before, after, or around a specific set of transitions.
+  class Callback
+    include EvalHelpers
+
+    class << self
+      # Determines whether to automatically bind the callback to the object
+      # being transitioned.  This only applies to callbacks that are defined as
+      # lambda blocks (or Procs).  Some integrations, such as DataMapper, handle
+      # callbacks by executing them bound to the object involved, while other
+      # integrations, such as ActiveRecord, pass the object as an argument to
+      # the callback.  This can be configured on an application-wide basis by
+      # setting this configuration to +true+ or +false+.  The default value
+      # is +false+.
+      #
+      # *Note* that the DataMapper and Sequel integrations automatically
+      # configure this value on a per-callback basis, so it does not have to
+      # be enabled application-wide.
+      #
+      # == Examples
+      #
+      # When not bound to the object:
+      #
+      #   class Vehicle
+      #     state_machine do
+      #       before_transition do |vehicle|
+      #         vehicle.set_alarm
+      #       end
+      #     end
+      #
+      #     def set_alarm
+      #       ...
+      #     end
+      #   end
+      #
+      # When bound to the object:
+      #
+      #   StateMachines::Callback.bind_to_object = true
+      #
+      #   class Vehicle
+      #     state_machine do
+      #       before_transition do
+      #         self.set_alarm
+      #       end
+      #     end
+      #
+      #     def set_alarm
+      #       ...
+      #     end
+      #   end
+      attr_accessor :bind_to_object
+
+      # The application-wide terminator to use for callbacks when not
+      # explicitly defined.  Terminators determine whether to cancel a
+      # callback chain based on the return value of the callback.
+      #
+      # See StateMachines::Callback#terminator for more information.
+      attr_accessor :terminator
+    end
+
+    # The type of callback chain this callback is for.  This can be one of the
+    # following:
+    # * +before+
+    # * +after+
+    # * +around+
+    # * +failure+
+    attr_accessor :type
+
+    # An optional block for determining whether to cancel the callback chain
+    # based on the return value of the callback.  By default, the callback
+    # chain never cancels based on the return value (i.e. there is no implicit
+    # terminator).  Certain integrations, such as ActiveRecord and Sequel,
+    # change this default value.
+    #
+    # == Examples
+    #
+    # Canceling the callback chain without a terminator:
+    #
+    #   class Vehicle
+    #     state_machine do
+    #       before_transition do |vehicle|
+    #         throw :halt
+    #       end
+    #     end
+    #   end
+    #
+    # Canceling the callback chain with a terminator value of +false+:
+    #
+    #   class Vehicle
+    #     state_machine do
+    #       before_transition do |vehicle|
+    #         false
+    #       end
+    #     end
+    #   end
+    attr_reader :terminator
+
+    # The branch that determines whether or not this callback can be invoked
+    # based on the context of the transition.  The event, from state, and
+    # to state must all match in order for the branch to pass.
+    #
+    # See StateMachines::Branch for more information.
+    attr_reader :branch
+
+    # Creates a new callback that can get called based on the configured
+    # options.
+    #
+    # In addition to the possible configuration options for branches, the
+    # following options can be configured:
+    # * <tt>:bind_to_object</tt> - Whether to bind the callback to the object involved.
+    #   If set to false, the object will be passed as a parameter instead.
+    #   Default is integration-specific or set to the application default.
+    # * <tt>:terminator</tt> - A block/proc that determines what callback
+    #   results should cause the callback chain to halt (if not using the
+    #   default <tt>throw :halt</tt> technique).
+    #
+    # More information about how those options affect the behavior of the
+    # callback can be found in their attribute definitions.
+    def initialize(type, *args, &block)
+      @type = type
+      raise ArgumentError, 'Type must be :before, :after, :around, or :failure' unless %i[before after around failure].include?(type)
+
+      options = args.last.is_a?(Hash) ? args.pop : {}
+      @methods = args
+      @methods.concat(Array(options.delete(:do)))
+      @methods << block if block_given?
+      raise ArgumentError, 'Method(s) for callback must be specified' unless @methods.any?
+
+      options = { bind_to_object: self.class.bind_to_object, terminator: self.class.terminator }.merge(options)
+
+      # Proxy lambda blocks so that they're bound to the object
+      bind_to_object = options.delete(:bind_to_object)
+      @methods.map! do |method|
+        bind_to_object && method.is_a?(Proc) ? bound_method(method) : method
+      end
+
+      @terminator = options.delete(:terminator)
+      @branch = Branch.new(options)
+    end
+
+    # Gets a list of the states known to this callback by looking at the
+    # branch's known states
+    def known_states
+      branch.known_states
+    end
+
+    # Runs the callback as long as the transition context matches the branch
+    # requirements configured for this callback.  If a block is provided, it
+    # will be called when the last method has run.
+    #
+    # If a terminator has been configured and it matches the result from the
+    # evaluated method, then the callback chain should be halted.
+    def call(object, context = {}, *, &)
+      if @branch.matches?(object, context)
+        run_methods(object, context, 0, *, &)
+        true
+      else
+        false
+      end
+    end
+
+    private
+
+    # Runs all of the methods configured for this callback.
+    #
+    # When running +around+ callbacks, this will evaluate each method and
+    # yield when the last method has yielded.  The callback will only halt if
+    # one of the methods does not yield.
+    #
+    # For all other types of callbacks, this will evaluate each method in
+    # order.  The callback will only halt if the resulting value from the
+    # method passes the terminator.
+    def run_methods(object, context = {}, index = 0, *args, &block)
+      case type
+      when :around
+        current_method = @methods[index]
+        if current_method
+          yielded = false
+          evaluate_method(object, current_method, *args) do
+            yielded = true
+            run_methods(object, context, index + 1, *args, &block)
+          end
+
+          throw :halt unless yielded
+        elsif block_given?
+          yield
+        end
+      else
+        @methods.each do |method|
+          result = evaluate_method(object, method, *args)
+          throw :halt if @terminator&.call(result)
+        end
+      end
+    end
+
+    # Generates a method that can be bound to the object being transitioned
+    # when the callback is invoked
+    def bound_method(block)
+      type = self.type
+      arity = block.arity
+      arity += 1 if arity >= 0 # Make sure the object gets passed
+      arity += 1 if arity == 1 && type == :around # Make sure the block gets passed
+
+      method = ->(object, *args) { object.instance_exec(*args, &block) }
+
+      # Proxy arity to the original block
+      (
+      class << method
+        self
+      end).class_eval do
+        define_method(:arity) { arity }
+      end
+
+      method
+    end
+  end
+end

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

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+# Load all of the core implementation required to use state_machine.  This
+# includes:
+# * StateMachines::MacroMethods which adds the state_machine DSL to your class
+# * A set of initializers for setting state_machine defaults based on the current
+#   running environment (such as within Rails)
+require 'state_machines/error'
+
+require 'state_machines/extensions'
+
+require 'state_machines/integrations'
+require 'state_machines/integrations/base'
+
+require 'state_machines/eval_helpers'
+
+require 'singleton'
+require 'state_machines/matcher'
+require 'state_machines/matcher_helpers'
+
+require 'state_machines/transition'
+require 'state_machines/transition_collection'
+
+require 'state_machines/branch'
+
+require 'state_machines/helper_module'
+require 'state_machines/callback'
+require 'state_machines/node_collection'
+
+require 'state_machines/state_context'
+require 'state_machines/state'
+require 'state_machines/state_collection'
+
+require 'state_machines/event'
+require 'state_machines/event_collection'
+
+require 'state_machines/path'
+require 'state_machines/path_collection'
+
+require 'state_machines/machine'
+require 'state_machines/machine_collection'
+
+require 'state_machines/macro_methods'

data/state_machines-0.201.0/lib/state_machines/core_ext/class/state_machine.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+Class.class_eval do
+  include StateMachines::MacroMethods
+end

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

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+# Loads all of the extensions to be made to Ruby core classes
+require 'state_machines/core_ext/class/state_machine'

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

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module StateMachines
+  # An error occurred during a state machine invocation
+  class Error < StandardError
+    # The object that failed
+    attr_reader :object
+
+    def initialize(object, message = nil) # :nodoc:
+      @object = object
+
+      super(message)
+    end
+  end
+
+  # An invalid integration was specified
+  class IntegrationNotFound < Error
+    def initialize(name)
+      super(nil, "#{name.inspect} is an invalid integration. #{error_message}")
+    end
+
+    def valid_integrations
+      "Valid integrations are: #{valid_integrations_name}"
+    end
+
+    def valid_integrations_name
+      Integrations.list.collect(&:integration_name)
+    end
+
+    def no_integrations
+      'No integrations registered'
+    end
+
+    def error_message
+      if Integrations.list.size.zero?
+        no_integrations
+      else
+        valid_integrations
+      end
+    end
+  end
+
+  # An invalid integration was registered
+  class IntegrationError < StandardError
+  end
+
+  # An invalid event was specified
+  class InvalidEvent < Error
+    # The event that was attempted to be run
+    attr_reader :event
+
+    def initialize(object, event_name) # :nodoc:
+      @event = event_name
+
+      super(object, "#{event.inspect} is an unknown state machine event")
+    end
+  end
+
+  # An invalid transition was attempted
+  class InvalidTransition < Error
+    # The machine attempting to be transitioned
+    attr_reader :machine
+
+    # The current state value for the machine
+    attr_reader :from
+
+    def initialize(object, machine, event) # :nodoc:
+      @machine = machine
+      @from_state = machine.states.match!(object)
+      @from = machine.read(object, :state)
+      @event = machine.events.fetch(event)
+      errors = machine.errors_for(object)
+
+      message = "Cannot transition #{machine.name} via :#{self.event} from #{from_name.inspect}"
+      message << " (Reason(s): #{errors})" unless errors.empty?
+      super(object, message)
+    end
+
+    # The event that triggered the failed transition
+    def event
+      @event.name
+    end
+
+    # The fully-qualified name of the event that triggered the failed transition
+    def qualified_event
+      @event.qualified_name
+    end
+
+    # The name for the current state
+    def from_name
+      @from_state.name
+    end
+
+    # The fully-qualified name for the current state
+    def qualified_from_name
+      @from_state.qualified_name
+    end
+  end
+
+  # A set of transition failed to run in parallel
+  class InvalidParallelTransition < Error
+    # The set of events that failed the transition(s)
+    attr_reader :events
+
+    def initialize(object, events) # :nodoc:
+      @events = events
+
+      super(object, "Cannot run events in parallel: #{events * ', '}")
+    end
+  end
+
+  # A method was called in an invalid state context
+  class InvalidContext < Error
+  end
+end