state_machines 0.6.0 → 0.30.0

data/lib/state_machines/machine/configuration.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module StateMachines
+  class Machine
+    module Configuration
+      # Initializes a new state machine with the given configuration.
+      def initialize(owner_class, *args, &)
+        options = args.last.is_a?(Hash) ? args.pop : {}
+        StateMachines::OptionsValidator.assert_valid_keys!(options, :attribute, :initial, :initialize, :action, :plural, :namespace, :integration, :messages, :use_transactions)
+
+        # Find an integration that matches this machine's owner class
+        @integration = if options.include?(:integration)
+                         options[:integration] && StateMachines::Integrations.find_by_name(options[:integration])
+                       else
+                         StateMachines::Integrations.match(owner_class)
+                       end
+
+        if @integration
+          extend @integration
+          options = (@integration.defaults || {}).merge(options)
+        end
+
+        # Add machine-wide defaults
+        options = { use_transactions: true, initialize: true }.merge(options)
+
+        # Set machine configuration
+        @name = args.first || :state
+        @attribute = options[:attribute] || @name
+        @events = EventCollection.new(self)
+        @states = StateCollection.new(self)
+        @callbacks = { before: [], after: [], failure: [] }
+        @namespace = options[:namespace]
+        @messages = options[:messages] || {}
+        @action = options[:action]
+        @use_transactions = options[:use_transactions]
+        @initialize_state = options[:initialize]
+        @action_hook_defined = false
+        self.owner_class = owner_class
+
+        # Merge with sibling machine configurations
+        add_sibling_machine_configs
+
+        # Define class integration
+        define_helpers
+        define_scopes(options[:plural])
+        after_initialize
+
+        # Evaluate DSL
+        instance_eval(&) if block_given?
+        self.initial_state = options[:initial] unless sibling_machines.any?
+      end
+
+      # Creates a copy of this machine in addition to copies of each associated
+      # event/states/callback, so that the modifications to those collections do
+      # not affect the original machine.
+      def initialize_copy(orig) # :nodoc:
+        super
+
+        @events = @events.dup
+        @events.machine = self
+        @states = @states.dup
+        @states.machine = self
+        @callbacks = { before: @callbacks[:before].dup, after: @callbacks[:after].dup, failure: @callbacks[:failure].dup }
+      end
+
+      # Sets the class which is the owner of this state machine.  Any methods
+      # generated by states, events, or other parts of the machine will be defined
+      # on the given owner class.
+      def owner_class=(klass)
+        @owner_class = klass
+
+        # Create modules for extending the class with state/event-specific methods
+        @helper_modules = helper_modules = { instance: HelperModule.new(self, :instance), class: HelperModule.new(self, :class) }
+        owner_class.class_eval do
+          extend helper_modules[:class]
+          include helper_modules[:instance]
+        end
+
+        # Add class-/instance-level methods to the owner class for state initialization
+        unless owner_class < StateMachines::InstanceMethods
+          owner_class.class_eval do
+            extend StateMachines::ClassMethods
+            include StateMachines::InstanceMethods
+          end
+
+          define_state_initializer if @initialize_state
+        end
+
+        # Record this machine as matched to the name in the current owner class.
+        # This will override any machines mapped to the same name in any superclasses.
+        owner_class.state_machines[name] = self
+      end
+
+      # Sets the initial state of the machine.  This can be either the static name
+      # of a state or a lambda block which determines the initial state at
+      # creation time.
+      def initial_state=(new_initial_state)
+        @initial_state = new_initial_state
+        add_states([@initial_state]) unless dynamic_initial_state?
+
+        # Update all states to reflect the new initial state
+        states.each { |state| state.initial = (state.name == @initial_state) }
+
+        # Output a warning if there are conflicting initial states for the machine's
+        # attribute
+        initial_state = states.detect(&:initial)
+        has_owner_default = !owner_class_attribute_default.nil?
+        has_conflicting_default = dynamic_initial_state? || !owner_class_attribute_default_matches?(initial_state)
+        return unless has_owner_default && has_conflicting_default
+
+        warn(
+          "Both #{owner_class.name} and its #{name.inspect} machine have defined " \
+          "a different default for \"#{attribute}\". Use only one or the other for " \
+          'defining defaults to avoid unexpected behaviors.'
+        )
+      end
+
+      # Gets the attribute name for the given machine scope.
+      def attribute(name = :state)
+        name == :state ? @attribute : :"#{self.name}_#{name}"
+      end
+    end
+  end
+end

data/lib/state_machines/machine/event_methods.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module StateMachines
+  class Machine
+    module EventMethods
+      # Defines one or more events for the machine and the transitions that can
+      # be performed when those events are run.
+      def event(*names, &)
+        options = names.last.is_a?(Hash) ? names.pop : {}
+        StateMachines::OptionsValidator.assert_valid_keys!(options, :human_name)
+
+        # Store the context so that it can be used for / matched against any event
+        # that gets added
+        @events.context(names, &) if block_given?
+
+        if names.first.is_a?(Matcher)
+          # Add any events referenced in the matcher.  When matchers are used,
+          # events are not allowed to be configured.
+          raise ArgumentError, "Cannot configure events when using matchers (using #{options.inspect})" if options.any?
+
+          events = add_events(names.first.values)
+        else
+          events = add_events(names)
+
+          # Update the configuration for the event(s)
+          events.each do |event|
+            event.human_name = options[:human_name] if options.include?(:human_name)
+
+            # Add any states that may have been referenced within the event
+            add_states(event.known_states)
+          end
+        end
+
+        events.length == 1 ? events.first : events
+      end
+
+      alias on event
+
+      # Creates a new transition that determines what to change the current state
+      # to when an event fires.
+      def transition(options)
+        raise ArgumentError, 'Must specify :on event' unless options[:on]
+
+        branches = []
+        options = options.dup
+        event(*Array(options.delete(:on))) { branches << transition(options) }
+
+        branches.length == 1 ? branches.first : branches
+      end
+
+      # Gets the list of all possible transition paths from the current state to
+      # the given target state.  If multiple target states are provided, then
+      # this will return all possible paths to those states.
+      def paths_for(object, requirements = {})
+        PathCollection.new(object, self, requirements)
+      end
+    end
+  end
+end

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