state_machines 0.20.0 → 0.30.0

data/lib/state_machines/machine/helper_generators.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module StateMachines
+  class Machine
+    module HelperGenerators
+      protected
+
+      # Adds helper methods for interacting with the state machine, including
+      # for states, events, and transitions
+      def define_helpers
+        define_state_accessor
+        define_state_predicate
+        define_event_helpers
+        define_path_helpers
+        define_action_helpers if define_action_helpers?
+        define_name_helpers
+      end
+
+      # Defines the initial values for state machine attributes.  Static values
+      # are set prior to the original initialize method and dynamic values are
+      # set *after* the initialize method in case it is dependent on it.
+      def define_state_initializer
+        define_helper :instance, <<-END_EVAL, __FILE__, __LINE__ + 1
+            def initialize(*)
+              self.class.state_machines.initialize_states(self) { super }
+            end
+        END_EVAL
+      end
+
+      # Adds reader/writer methods for accessing the state attribute
+      def define_state_accessor
+        attribute = self.attribute
+
+        @helper_modules[:instance].class_eval { attr_reader attribute } unless owner_class_ancestor_has_method?(:instance, attribute)
+        @helper_modules[:instance].class_eval { attr_writer attribute } unless owner_class_ancestor_has_method?(:instance, "#{attribute}=")
+      end
+
+      # Adds predicate method to the owner class for determining the name of the
+      # current state
+      def define_state_predicate
+        call_super = owner_class_ancestor_has_method?(:instance, "#{name}?") ? true : false
+        define_helper :instance, <<-END_EVAL, __FILE__, __LINE__ + 1
+            def #{name}?(*args)
+              args.empty? && (#{call_super} || defined?(super)) ? super : self.class.state_machine(#{name.inspect}).states.matches?(self, *args)
+            end
+        END_EVAL
+      end
+
+      # Adds helper methods for getting information about this state machine's
+      # events
+      def define_event_helpers
+        # Gets the events that are allowed to fire on the current object
+        define_helper(:instance, attribute(:events)) do |machine, object, *args|
+          machine.events.valid_for(object, *args).map(&:name)
+        end
+
+        # Gets the next possible transitions that can be run on the current
+        # object
+        define_helper(:instance, attribute(:transitions)) do |machine, object, *args|
+          machine.events.transitions_for(object, *args)
+        end
+
+        # Fire an arbitrary event for this machine
+        define_helper(:instance, "fire_#{attribute(:event)}") do |machine, object, event, *args|
+          machine.events.fetch(event).fire(object, *args)
+        end
+
+        # Add helpers for tracking the event / transition to invoke when the
+        # action is called
+        return unless action
+
+        event_attribute = attribute(:event)
+        define_helper(:instance, event_attribute) do |machine, object|
+          # Interpret non-blank events as present
+          event = machine.read(object, :event, true)
+          event && !(event.respond_to?(:empty?) && event.empty?) ? event.to_sym : nil
+        end
+
+        # A roundabout way of writing the attribute is used here so that
+        # integrations can hook into this modification
+        define_helper(:instance, "#{event_attribute}=") do |machine, object, value|
+          machine.write(object, :event, value, true)
+        end
+
+        event_transition_attribute = attribute(:event_transition)
+        define_helper :instance, <<-END_EVAL, __FILE__, __LINE__ + 1
+              protected; attr_accessor #{event_transition_attribute.inspect}
+        END_EVAL
+      end
+
+      # Adds helper methods for getting information about this state machine's
+      # available transition paths
+      def define_path_helpers
+        # Gets the paths of transitions available to the current object
+        define_helper(:instance, attribute(:paths)) do |machine, object, *args|
+          machine.paths_for(object, *args)
+        end
+      end
+
+      # Adds helper methods for accessing naming information about states and
+      # events on the owner class
+      def define_name_helpers
+        # Gets the humanized version of a state
+        define_helper(:class, "human_#{attribute(:name)}") do |machine, klass, state|
+          machine.states.fetch(state).human_name(klass)
+        end
+
+        # Gets the humanized version of an event
+        define_helper(:class, "human_#{attribute(:event_name)}") do |machine, klass, event|
+          machine.events.fetch(event).human_name(klass)
+        end
+
+        # Gets the state name for the current value
+        define_helper(:instance, attribute(:name)) do |machine, object|
+          machine.states.match!(object).name
+        end
+
+        # Gets the human state name for the current value
+        define_helper(:instance, "human_#{attribute(:name)}") do |machine, object|
+          machine.states.match!(object).human_name(object.class)
+        end
+      end
+    end
+  end
+end

data/lib/state_machines/machine/integration.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module StateMachines
+  class Machine
+    module Integration
+      # Marks the given object as invalid with the given message.
+      #
+      # By default, this is a no-op.
+      def invalidate(_object, _attribute, _message, _values = []); end
+
+      # Gets a description of the errors for the given object.  This is used to
+      # provide more detailed information when an InvalidTransition exception is
+      # raised.
+      def errors_for(_object)
+        ''
+      end
+
+      # Resets any errors previously added when invalidating the given object.
+      #
+      # By default, this is a no-op.
+      def reset(_object); end
+
+      # Generates a user-friendly name for the given message.
+      def generate_message(name, values = [])
+        format(@messages[name] || @messages[:invalid_transition] || default_messages[name] || default_messages[:invalid_transition], state: values.first)
+      end
+
+      # Runs a transaction, yielding the given block.
+      #
+      # By default, this is a no-op.
+      def within_transaction(object, &)
+        if use_transactions && respond_to?(:transaction, true)
+          transaction(object, &)
+        else
+          yield
+        end
+      end
+
+      protected
+
+      # Runs additional initialization hooks.  By default, this is a no-op.
+      def after_initialize; end
+
+      # Always yields
+      def transaction(_object)
+        yield
+      end
+
+      # Gets the initial attribute value defined by the owner class (outside of
+      # the machine's definition). By default, this is always nil.
+      def owner_class_attribute_default
+        nil
+      end
+
+      # Checks whether the given state matches the attribute default specified
+      # by the owner class
+      def owner_class_attribute_default_matches?(state)
+        state.matches?(owner_class_attribute_default)
+      end
+
+      private
+
+      # Gets the default messages that can be used in the machine for invalid
+      # transitions.
+      def default_messages
+        { invalid_transition: '%<state>s cannot transition via "%<event>s"' }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,101 @@
+# 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.
+      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.
+      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/lib/state_machines/machine/utilities.rb

@@ -0,0 +1,85 @@
+# 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
+
+      # Looks up the ancestor class that has the given method defined.  This
+      # is used to find the method owner which is used to determine where to
+      # define new methods.
+      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/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