state_gate 1.2.3

data/lib/state_gate/engine/configurator.rb

@@ -0,0 +1,230 @@
+# frozen_string_literal: true
+
+module StateGate
+  class Engine
+    ##
+    # = Description
+    #
+    # Parses the configuration for StateGate::Engine.
+    #
+    # The configuration defines the state names, allowed transitions and a number of
+    # options to help customise the _state-gate_ to your exact preference.
+    #
+    # Options include:
+    #
+    # === | state
+    # Required name for the new state, supplied as a Symbol. The +state-gate+ requires
+    # a minimum of two states to be defined.
+    #     state :state_name
+    #
+    #
+    # [:transitions_to]
+    #   An optional list of the other state that this state is allowed to change to.
+    #     state :state_1, transtions_to: [:state_2, :state_3, :state_4]
+    #     state :state_2, transtions_to: :state_4
+    #     state :state_3, transtions_to: :any
+    #     state :state_4
+    #
+    # [:human]
+    #   An optional String name to used when displaying gthe state in a view. If no
+    #   name is specified, it will default to +:state.titleized+.
+    #     state :state_1, transtions_to: [:state_2, :state_3], human: "My State"
+    #
+    #
+    # === | default
+    # Optional setting to specify the default state for a new object. The state name
+    # is given as a Symbol.
+    #     default :state_name
+    #
+    #
+    # === | prefix
+    # Optional setting to add a given Symbol before each state name when using Class Scopes.
+    # This helps to differential between multiple attributes that have similar state names.
+    #     prefix :before  # => Class.before_active
+    #
+    #
+    # === | suffix
+    # Optional setting to add a given Symbol after each state name when using Class Scopes.
+    # This helps to differential between multiple attributes that have similar state names.
+    #     suffix :after  # => Class.active_after
+    #
+    #
+    # === | make_sequential
+    # Optional setting to automatically add transitions from each state to both the
+    # preceeding and following states.
+    #     make_sequential
+    #
+    # [:one_way]
+    #   Option to restrict the generated transitions to one directtion only: from each
+    #   state to the follow state.
+    #     make_sequential :one_way
+    #
+    # [:loop]
+    #   Option to add transitions from the last state to the first and, unless +:one_way+
+    #   is specified, also from the first state to the last.
+    #     make_sequential :one_way, :loop
+    #
+    #
+    # === | no_scopes
+    # Optional setting to disable the generation of Class Scope helpers methods.
+    #     no_scopes
+    #
+    module Configurator
+
+      # = Private
+      # ======================================================================
+      private
+
+
+      # ======================================================================
+      #  Configuration Commands
+      # ======================================================================
+
+
+      # Execute the provided configuration.
+      #
+      # ==== actions
+      #
+      #   + create sequence links and transitions
+      #   + create scope names
+      #   + remove duplicate transitions for each state
+      #
+      #   + verify there are multiple valid state names
+      #   + verify all transitions lead to existing states
+      #   + verify each state, except the default, can be reached from a transition
+      #
+      def parse_configuration(&config)
+        exec_configuration(&config)
+
+        generate_sequences
+        generate_scope_names
+
+        assert_states_are_valid
+        assert_transitions_exist
+        assert_uniq_transitions
+        assert_any_has_been_expanded
+        assert_all_transitions_are_states
+        assert_all_states_are_reachable
+      end
+
+
+
+      # Run the configuration commands.
+      #
+      # ==== actions
+      #
+      #   + create sequence links and transitions
+      #   + create scope names
+      #   + remove duplicate transitions for each state
+      #
+      #   + verify there are multiple valid state names
+      #   + verify all transitions lead to existing states
+      #   + verify each state, except the default, can be reached from a transition
+      #
+      def exec_configuration(&config)
+        instance_exec(&config)
+      rescue NameError => e
+        err_command = e.to_s.gsub('undefined local variable or method `', '')
+                       .split("'")
+                       .first
+        cerr :bad_command, cmd: err_command
+      end
+
+
+
+      # ======================================================================
+      #  Assertions
+      # ======================================================================
+
+      # Ensure there are enough states and the default is a valid state, setting
+      # the default to the first state if required.
+      #
+      def assert_states_are_valid
+        state_names = @states.keys
+
+        # are there states
+        cerr(:states_missing_err) if state_names.blank?
+
+        # is there more than one state
+        cerr(:single_state_err) if state_names.one?
+
+        # set the deafult state if needed, otherwise check it is a valid state
+        if @default
+          cerr(:default_state_err) unless state_names.include?(@default)
+        else
+          @default = state_names.first
+        end
+      end
+
+
+
+      # Ensure that transitions have been specified.  If not, then add the transitions
+      # to allow every stater to transition to another state and flag the engine as
+      # transitionless, so we don't add any validation methods.
+      #
+      def assert_transitions_exist
+        return if @states.map { |_state, opts| opts[:transitions_to] }.uniq.flatten.any?
+
+        @transitionless = true
+        @states.keys.each do |key|
+          @states[key][:transitions_to] = @states.keys - [key]
+        end
+      end
+
+
+
+      # Ensure that there is only one of reach transition
+      #
+      def assert_uniq_transitions
+        @states.each { |_state, opts| opts[:transitions_to].uniq! }
+      end
+
+
+
+      # Ensure that the :any transition is expanded or raise an exception
+      # if it's included with other transitions
+      def assert_any_has_been_expanded
+        @states.each do |state_name, opts|
+          if opts[:transitions_to] == [:any]
+            @states[state_name][:transitions_to] = @states.keys - [state_name]
+
+          elsif opts[:transitions_to].include?(:any)
+            cerr(:any_transition_err, state: state_name, kattr: true)
+          end
+        end
+      end
+
+
+
+      # Ensure all transitions are to valid states.
+      #
+      # Replaces transition to :any with a list of all states
+      # Raises an exception if :any in included with a list of other transitions
+      #
+      def assert_all_transitions_are_states
+        @states.each do |state_name, opts|
+          opts[:transitions_to].each do |transition|
+            unless @states.keys.include?(transition)
+              cerr(:transition_state_err, state: state_name, transition: transition, kattr: true)
+            end
+          end
+        end
+      end
+
+
+
+      # Ensure there is a transition leading to every non-default state.
+      #
+      def assert_all_states_are_reachable
+        # is there a transition to every state except the default.
+        transitions   = @states.map { |_state, opts| opts[:transitions_to] }.flatten.uniq
+        adrift_states = (@states.keys - transitions - [@default])
+        return if adrift_states.blank?
+
+        states = adrift_states.map { |s| ':' + s.to_s }.to_sentence
+        cerr(:transitionless_states_err, states: states, kattr: true)
+      end
+
+    end # ConfigurationMethods
+  end # Engine
+end # StateGate

data/lib/state_gate/engine/errator.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module StateGate
+  class Engine
+    ##
+    # = Description
+    #
+    # Adds error reporting methods to a StateMachine::Engine
+    # * all error messages are I18n configured
+    # * method names are deliberately short to encourage code readability with
+    #   if/unless one-liners
+    module Errator
+
+      #  Private
+      # ======================================================================
+      private
+
+      # Format the given value and report an ArgumentError
+      #
+      def invalid_state_error(val)
+        case val
+        when NilClass
+          aerr :invalid_state_err, val: "'nil'", kattr: true
+        when Symbol
+          aerr :invalid_state_err, val: ":#{val}", kattr: true
+        else
+          aerr :invalid_state_err, val: "'#{val&.to_s}'", kattr: true
+        end
+      end
+
+
+
+      # Report a ConfigurationError, including the Klass#attr variable.
+      #
+      def cerr(err, **args)
+        args[:kattr] = "#{@klass}##{@attribute}" if args[:kattr] == true
+        key          = "state_gate.engine.config.#{err}"
+        fail ConfigurationError, I18n.t(key, **args)
+      end
+
+
+
+      # Report a RuntimeError, including the Klass#attr variable.
+      #
+      def rerr(err, **args)
+        args[:kattr] = "#{@klass}##{@attribute}" if args[:kattr] == true
+        key          = "state_gate.engine.#{err}"
+        fail I18n.t(key, **args)
+      end
+
+
+
+      # Report an ArgumentError, including the Klass#attr variable.
+      #
+      def aerr(err, **args)
+        args[:kattr] = "#{@klass}##{@attribute}" if args[:kattr] == true
+        key          = "state_gate.engine.#{err}"
+        fail ArgumentError, I18n.t(key, **args)
+      end
+
+    end # Errator
+  end # Engine
+end # StateGate

data/lib/state_gate/engine/fixer.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module StateGate
+  class Engine
+    ##
+    # = Description
+    #
+    # Provides prefix and suffix helper methods for StateGate::Engine.
+    #
+    module Fixer
+
+      # ======================================================================
+      #   Configuration Methods
+      # ======================================================================
+
+      # A phrase to add before state names when using Class Scopes.
+      # This helps differential attributes that have similar state names.
+      # (Symbol | optional)
+      #
+      #   prefix :before  # => Class.before_active
+      #
+      def prefix(val = nil)
+        cerr(:prefix_type_err, kattr: true) unless val.is_a?(Symbol)
+        cerr(:prefix_multiple_err, kattr: true) if @prefix
+        @prefix = "#{val.to_s.downcase}_"
+      end # prefix
+
+
+
+      # A phrase to add before state names when using Class Scopes.
+      # This helps differential attributes that have similar state names.
+      # (Symbol | optional)
+      #
+      #   suffix :after  # => Class.active_after
+      #
+      def suffix(val = nil)
+        cerr(:suffix_type_err, kattr: true) unless val.is_a?(Symbol)
+        cerr(:suffix_multiple_err, kattr: true) if @suffix
+        @suffix = "_#{val.to_s.downcase}"
+      end # suffix
+
+
+
+      # ======================================================================
+      #   Helper Methods
+      # ======================================================================
+
+      ##
+      # Returns the defined prefix for the state_gate, or an empty string if no
+      # prefix has been defined.
+      #
+      #   .state_prefix   # => 'my_prefix'
+      #   .state_prefix   # => ''
+      #
+      def state_prefix
+        @prefix
+      end
+
+
+
+      ##
+      # Returns the defined suffix for the state_gate, or an empty string if no
+      # suffix has been defined.
+      #
+      #   .state_suffix   # => 'my_suffix'
+      #   .state_suffix   # => ''
+      #
+      def state_suffix
+        @suffix
+      end
+
+
+    end # Sequencer
+  end # Engine
+end # StateGate

data/lib/state_gate/engine/scoper.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module StateGate
+  class Engine
+    ##
+    # = Description
+    #
+    # Provides scope helper methods for StateGate::Engine.
+    #
+    module Scoper
+
+      # ======================================================================
+      #   Configuration Methods
+      # ======================================================================
+
+      # Disables the generation of Class Scope helpers methods
+      #
+      #   no_scopes
+      #
+      def no_scopes
+        @scopes = false
+      end
+
+
+
+      # Generate the scope name to use for each state.
+      #
+      def generate_scope_names
+        @states.each do |state, opts|
+          opts[:scope_name] = "#{@prefix}#{state}#{@suffix}"
+        end # each state
+      end # generate_sequences
+
+
+
+      # ======================================================================
+      #   Helper Methods
+      # ======================================================================
+
+      ##
+      # Returns TRUE if scope methods should be added to the model, otherwise FALSE.
+      #
+      #   .include_scopes?  # => true
+      #
+      def include_scopes?
+        !!@scopes
+      end
+
+
+
+      ##
+      # Returns the scope name for the given state. Scope names are generated by
+      # concatenating the prefix, state name and suffix
+      #
+      #   .scope_name_for_state(:active)      # => 'active'
+      #   .scope_name_for_state(:pending)     # => 'pending_status'
+      #   .scope_name_for_state(:archived)    # => 'with_archived_status'
+      #
+      def scope_name_for_state(state_name = nil)
+        state = assert_valid_state!(state_name)
+        @states[state][:scope_name]
+      end
+
+    end # Sequencer
+  end # Engine
+end # StateGate

data/lib/state_gate/engine/sequencer.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module StateGate
+  class Engine
+    ##
+    # = Description
+    #
+    # Provides state sequence helper methods for StateGate::Engine.
+    #
+    # All methods raise an error if +sequential?+ is FALSE
+    #
+    module Sequencer
+
+      # ======================================================================
+      #   Configuration Methods
+      # ======================================================================
+
+      # Automatically add transitions from each state to the preceeding and following states.
+      #   make_sequential
+      #
+      # [:one_way]
+      #   Only adds tranitions from each state to the follow state. (optional)
+      #     make_sequential :one_way
+      #
+      # [:loop]
+      #   Adds transitions from the last state to the first and from the first to the last
+      #   (unless also :one_way) (optional)
+      #     make_sequential :one_way, :loop
+      #
+      def make_sequential(*args)
+        @sequential         = true
+        @sequential_loop    = true if args.include?(:loop)
+        @sequential_one_way = true if args.include?(:one_way)
+      end
+
+
+
+      # Add sequence hooks if sequential requested.
+      #
+      def generate_sequences
+        return unless sequential?
+
+        add_previous_sequential_state
+        add_next_sequential_state
+        loop_sequence
+      end # generate_sequences
+
+
+
+      # Add the previous sequential state
+      #
+      def add_previous_sequential_state
+        return if @sequential_one_way
+
+        previous_state = nil
+        @states.keys.each do |state|
+          if previous_state
+            @states[state][:previous_state] =  previous_state
+            @states[state][:transitions_to] << previous_state
+          end
+          previous_state = state
+        end
+      end
+
+
+
+      # Add the next sequential state
+      #
+      def add_next_sequential_state
+        next_state = nil
+        @states.keys.reverse.each do |state|
+          if next_state
+            @states[state][:next_state] =      next_state
+            @states[state][:transitions_to] << next_state
+          end
+          next_state = state
+        end
+      end
+
+
+
+      # Add the first and last transitions to complete the sequential loop.
+      #
+      def loop_sequence
+        return unless @sequential_loop
+
+        first_state = @states.keys.first
+        last_state  = @states.keys.last
+
+        @states[last_state][:next_state] =      first_state
+        @states[last_state][:transitions_to] << first_state
+
+        return if @sequential_one_way
+
+        @states[first_state][:previous_state] =  last_state
+        @states[first_state][:transitions_to] << last_state
+      end # loop_sequence
+
+
+
+      # ======================================================================
+      #   Helper Methods
+      # ======================================================================
+
+      ##
+      # return TRUE if the state_gate is sequential, otherwise FALSE.
+      #
+      #   .sequential?  # => TRUE
+      #
+      def sequential?
+        !!@sequential
+      end
+
+    end # Sequencer
+  end # Engine
+end # StateGate