state_gate 1.2.3

data/lib/state_gate/engine/stator.rb

@@ -0,0 +1,225 @@
+# frozen_string_literal: true
+
+module StateGate
+  class Engine
+    ##
+    # = Description
+    #
+    # Provides state helper methods for StateGate::Engine.
+    #
+    module Stator
+
+      # ======================================================================
+      #   Configursation Methods
+      # ======================================================================
+
+      # Add a new +state+.
+      #
+      # [:state_name*]
+      #   The name for the new state. (Symbol | required)
+      #     state :state_name
+      #
+      #
+      # [:transitions_to]
+      #   A list of other state that this state may change to. (Array | optional)
+      #     state :state_name, transtions_to: [:state_1, :state_4, :state_5]
+      #
+      # [:human]
+      #   A display name for the state used in views.
+      #   (String | optoinal | default: state.titleized)
+      #     state :state_name, transtions_to: [:state_1, :state_4, :state_5], human: "My State"
+      #
+      def state(name, opts = {})
+        name = StateGate.symbolize(name)
+        assert_valid_state_name(name)
+        assert_valid_opts(opts, name)
+
+        # add the state
+        @states[name] = state_template.merge({ human: opts[:human] || name.to_s.titleize })
+
+        # add the state transitions
+        Array(opts[:transitions_to]).each do |transition|
+          @states[name][:transitions_to] << StateGate.symbolize(transition)
+        end
+      end # state
+
+
+
+      # The name for the default state for a new object. (String | required)
+      #
+      #   default :state_name
+      #
+      def default(val = nil)
+        cerr(:default_type_err, kattr: true) unless val.is_a?(Symbol)
+        cerr(:default_repeat_err, kattr: true) if   @default
+        @default = StateGate.symbolize(val)
+      end
+
+
+
+      # ======================================================================
+      #   Helper Methods
+      # ======================================================================
+
+      ##
+      # Returns an Array defined states.
+      #
+      #   .states  # => [:pending, :active, :suspended, :archived]
+      #
+      def states
+        @states.keys
+      end
+
+
+
+      ##
+      # Ensures the given value is a valid state name.
+      #
+      # [value]
+      #   A String or Symbol state name.
+      #
+      #     .assert_valid_state!(:active)    # => :active
+      #     .assert_valid_state!('PENDING')  # => :pending
+      #     .assert_valid_state!(:dummy)     # => ArgumentError
+      #
+      #
+      # [Note]
+      #   Valid state names preceeded with +force_+ are also allowed.
+      #
+      #     .assert_valid_state!(:force_active)  # => :force_active
+      #
+      # Returns the Symbol state name
+      # Raises an exception if the value is not a valid state name.
+      #
+      def assert_valid_state!(value)
+        state_name                      = StateGate.symbolize(value)
+        unforced_state                  = state_name.to_s.remove(/^force_/).to_sym
+        invalid_state_error(value) unless @states.keys.include?(unforced_state)
+        state_name
+      end
+
+
+
+      ##
+      # Returns an Array of the human display names for each defined state.
+      #
+      #   human_states  # => ['Pending Activation', 'Active', 'Suspended By Admin']
+      #
+      def human_states
+        @states.map { |_k, v| v[:human] }
+      end
+
+
+
+      ##
+      # Returns the human display name for a given state.
+      #
+      #   .human_state_for(:pending)  # => 'Panding Activation'
+      #   .human_state_for(:active)   # => 'Active'
+      #
+      def human_state_for(state)
+        state_name = assert_valid_state!(state)
+        @states[state_name][:human]
+      end
+
+
+
+      ##
+      # Return an Array of states, with their human display names, ready for
+      # use in a form select.
+      #
+      # sorted - TRUE is the states should be sorted by human name, defaults to false
+      #
+      #   .states_for_select        # => [['Pending Activation', 'pending'],
+      #                             #     ['Active', 'active'],
+      #                             #     ['Suspended by Admin', 'suspended']]
+      #
+      #   .states_for_select(true)  # => [['Active', 'active'],
+      #                             #     ['Pending Activation', 'pending'],
+      #                             #     ['Suspended by Admin', 'suspended']]
+      #
+      def states_for_select(sorted = false)
+        result = []
+        if sorted
+          @states.sort_by { |_k, v| v[:human] }
+                 .each { |state, opts| result << [opts[:human], state.to_s] }
+        else
+          @states.each { |state, opts| result << [opts[:human], state.to_s] }
+        end
+        result
+      end
+
+
+
+      ##
+      # Return the raw states hash, allowing inspection of the core engine states.
+      #
+      #   .raw_states  # => { pending: { transitions_to: [:active],
+      #                #                 human:          'Pending Activation'},
+      #                #      active:  { transitions_to: [:pending],
+      #                #                 human:          'Active'}}
+      #
+      def raw_states
+        @states
+      end
+
+
+
+      ##
+      # Returns the state_gate default state
+      #
+      #   .default_state   # => :pending
+      #
+      def default_state
+        @default
+      end
+
+
+
+      # ======================================================================
+      #   Private
+      # ======================================================================
+      private
+
+
+
+      # return a Hash with the state keys defined.
+      def state_template
+        {
+          transitions_to: [],
+          previous_state: nil,
+          next_state:     nil,
+          scope_name:     nil,
+          human:          ''
+        }
+      end
+
+
+
+      # fail if the supplied name is not a symbol, already added
+      # or starts with 'not_' or 'force'.
+      #
+      def assert_valid_state_name(name)
+        cerr(:state_type_err, kattr: true) unless name.is_a?(Symbol)
+        cerr(:state_repeat_err, state: name, kattr: true)     if @states.key?(name)
+        cerr(:state_not_name_err, state: name, kattr: true)   if name.to_s.start_with?('not_')
+        cerr(:state_force_name_err, state: name, kattr: true) if name.to_s.start_with?('force_')
+      end
+
+
+
+      # Fail if opts is not a hash, has non-symbol keys or non-symbol transitions.
+      #
+      def assert_valid_opts(opts, state_name)
+        unless opts.keys.reject { |k| k.is_a?(Symbol) }.blank?
+          cerr(:state_opts_key_type_err, state: state_name, kattr: true)
+        end
+
+        return if Array(opts[:transitions_to]).reject { |k| k.is_a?(Symbol) }.blank?
+
+        cerr(:transition_key_type_err, state: state_name, kattr: true)
+      end
+
+    end # Stater
+  end # Engine
+end # StateGate

data/lib/state_gate/engine/transitioner.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module StateGate
+  class Engine
+    ##
+    # = Description
+    #
+    # Provides transition helper methods for StateGate::Engine.
+    #
+    module Transitioner
+
+      ##
+      # Returns TRUE if every state can transition to every other state, rendering
+      # transitions pointless.
+      #
+      #   .transitionless?  # => true
+      #
+      def transitionless?
+        !!@transitionless
+      end
+
+
+
+      ##
+      # Returns a Hash of states and allowed transitions.
+      #
+      #   .transitions  # => { pending:   [:active],
+      #                 #      ativive:   [:suspended, :archived],
+      #                 #      suspended: [:active, :archived],
+      #                 #      archived:  [] }
+      #
+      def transitions
+        @transitions ||= begin
+          transitions = {}
+          @states.each { |k, v| transitions[k] = v[:transitions_to] } # rubocop:disable Layout/ExtraSpacing
+          transitions
+        end
+      end
+
+
+
+      ##
+      # Return an Array of allowed transitions for the given state
+      #
+      #   .transitions_for_state(:active) # => [:suspended, :archived]
+      #
+      def transitions_for_state(state)
+        state_name = assert_valid_state!(state)
+        transitions[state_name]
+      end
+
+
+
+      ##
+      # Returns TRUE if a transition is allowed, otherwise raises an exception.
+      #
+      #   .assert_valid_transition!(:pending, :active) # => true
+      #   .assert_valid_transition!(:active, :pending) # => ArgumentError
+      #
+      def assert_valid_transition!(current_state = nil, new_state = nil)
+        from_state = assert_valid_state!(current_state)
+        to_state   = assert_valid_state!(new_state)
+
+        return true if to_state == from_state
+        return true if to_state.to_s.start_with?('force_')
+        return true if @states[from_state][:transitions_to].include?(to_state)
+
+        aerr(:invalid_state_transition_err, from: from_state, to: to_state, kattr: true)
+      end
+
+    end # Sequencer
+  end # Engine
+end # StateGate

data/lib/state_gate/engine.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+Dir[File.join(__dir__, 'engine', '*.rb')].sort.each { |file| require file }
+
+module StateGate
+  ##
+  # = Description
+  #
+  # Contains a list of the _state-gate_ defined states, allowed transitions and configuration
+  # options.
+  #
+  # The engine is queried by all helper methods to validate states and allowed transitions.
+  #
+  class Engine
+
+    include Configurator
+    include Transitioner
+    include Sequencer
+    include Errator
+    include Scoper
+    include Stator
+    include Fixer
+
+
+
+    # ======================================================================
+    # = Private
+    # ======================================================================
+    private
+
+    # Initialize the engine, setting the Class and attribute for the new engine
+    # and parsing the provided configuration.
+    #
+    #   StateGate::Engine.new(MyKlass, :status) do
+    #     ... configuration ...
+    #   end
+    #
+    def initialize(klass, attribute, &config)
+      aerror(:klass_type_err)            unless klass.respond_to?(:to_s)
+      aerror(:attribute_type_err)        unless attribute.is_a?(Symbol)
+      aerror(:missing_config_block_err)  unless block_given?
+
+      @klass     = klass
+      @attribute = StateGate.symbolize(attribute)
+
+      set_defaults
+
+      parse_configuration(&config)
+    end
+
+
+
+    # Set the class variables with default values
+    def set_defaults
+      @states         = {}
+      @default        = nil
+      @prefix         = nil
+      @suffix         = nil
+      @scopes         = true
+      @sequential     = false
+      @transitionless = false
+    end
+
+  end # Engine
+end # StateGate

data/lib/state_gate/locale/builder_en.yml

@@ -0,0 +1,14 @@
+en:
+  state_gate:
+    builder:
+
+      non_class_err:              "StateGate requires %{klass} to be a Class."
+      non_active_record_err:      "StateGate requires %{klass} to derive from ActiveRecord."
+      missing_attribute_err:      "Missing attribute name when using 'state_gate' in class '%{klass}'."
+      attribute_type_err:         "StateGate <attr> must be a Symbol."
+      non_db_attr_err:            "%{kattr} is not a database attribute."
+      non_string_column_err:      "StateGate requires %{kattr} to be a database :string type."
+      existing_state_gate_err:    "An StateGate has already been defined for %{kattr}."
+      conflict_err:               "StateGate for %{klass}#%{attribute} will generate %{type} method '%{method_name}', which is already defined by %{source}."
+
+

data/lib/state_gate/locale/engine_en.yml

@@ -0,0 +1,58 @@
+en:
+  state_gate:
+    engine:
+
+      # ======================================================================
+      # = Engine
+      # ======================================================================
+
+      attribute_type_err:       "The provided attribute must be a Symbol."
+      invalid_state_err:        "%{val} is not valid state for %{kattr}."
+      klass_type_err:           "The proved class must be a Class or String."
+      missing_config_block_err: "No configuration block provided."
+
+
+
+      # ======================================================================
+      # = Engine Configuration
+      # ======================================================================
+
+      config:
+        bad_command:               "'%{cmd}' is not a valid configuration option."
+        default_repeat_err:        "default for %{kattr} has been specified multiple times."
+        default_state_err:         "The default set for %{kattr} is not a valid state."
+        default_type_err:          "default for %{kattr} must be a Symbol."
+        prefix_multiple_err:       "prefix for %{kattr} has been defined multiple times."
+        prefix_type_err:           "prefix for %{kattr} must be a Symbol."
+        single_state_err:          "%{kattr} needs at least two states defined."
+        state_force_name_err:      "%{kattr}:%{state} states cannot begin with 'force_'."
+        state_not_name_err:        "%{kattr}:%{state} states cannot begin with 'not_'."
+        state_opts_key_type_err:   "options for %{kattr}:%{state} must be Symbols."
+        state_repeat_err:          "%{kattr}:%{state} has been defined multiple times."
+        state_type_err:            "states for %{kattr} must be a Symbol."
+        states_missing_err:        "no states have been defined for %{kattr}."
+        suffix_multiple_err:       "suffix for %{kattr} has been defined multiple times."
+        suffix_type_err:           "suffix for %{kattr} must be a Symbol."
+        transition_key_type_err:   "transitions for %{kattr}:%{state} must be Symbols."
+        any_transition_err:        "when transitioning to :any on %{kattr}:%{state}, :any must be the only transition."
+        transition_state_err:      "%{kattr} transitions from :%{state} to invalid state :%{transition}."
+        transitionless_states_err: "There are no state transitions leading to %{kattr} %{states}."
+
+
+
+      # ======================================================================
+      # = Engine Sequencer
+      # ======================================================================
+
+      non_sequential_err: "%{kattr} is not sequential and does not implement sequence methods."
+
+
+
+      # ======================================================================
+      # = Engine Transitioner
+      # ======================================================================
+
+      invalid_state_transition_err: "%{kattr} cannot transition from :%{from} to :%{to}."
+
+
+

data/lib/state_gate/locale/state_gate_en.yml

@@ -0,0 +1,5 @@
+en:
+  state_gate:
+    non_symbol_sm_name_err: "StateGate#state_method_name must be a Symbol"
+    included_err:           "StateGate requires %{base} to derive from ActiveRecord."
+    extended_err:           "%{base} should use 'include StateGate' and not 'extend StateGate'."

data/lib/state_gate/rspec/allow_transitions_on.rb

@@ -0,0 +1,259 @@
+# frozen_string_literal: true
+
+##
+# = Description
+#
+# RSpec matcher to verify allowed state transitions.
+#
+# [:source_obj]
+#   The Class or Instance to be tested.
+#
+# [:attr_name]
+#   The attrbute being tested.
+#
+# [:from]
+#   The state being transtioned from
+#
+# [:to]
+#   The states being transitions to
+#
+#  expect(User).to allow_transitions_on(:status).from(:active).to(:suspended, :archived)
+#
+# Fails if a given transitions is not allowed, or an allowed transition is missing.
+#
+RSpec::Matchers.define :allow_transitions_on do |attr_name| # rubocop:disable Metrics/BlockLength
+  ##
+  # Expect the given attribute state to match all given transitions.
+  #
+  match do |source_obj| # :nodoc:
+    # validate we have a state engine and parameters
+    return false unless valid_setup?(attr_name, source_obj)
+
+    allowed_transitions  = source_obj.stateables[@key]
+                                     .transitions_for_state(@state)
+    expected_transitions = @to.map(&:to_s).map(&:to_sym)
+    @missing_states      = allowed_transitions - expected_transitions
+    @extra_states        = expected_transitions - allowed_transitions
+
+    @error = :missing_states if @missing_states.any?
+    @error = :extra_states   if @extra_states.any?
+
+    @error ? false : true
+  end
+
+
+
+  # Expect the attribute state not to have any given transitions.
+  #
+  match_when_negated do |source_obj|
+    # validate we have a state engine and parameters
+    return false unless valid_setup?(attr_name, source_obj)
+
+    allowed_transitions  = source_obj.stateables[@key]
+                                     .transitions_for_state(@state)
+    expected_transitions = @to.map(&:to_s).map(&:to_sym)
+    remaining_states     = expected_transitions - allowed_transitions
+
+    unless remaining_states.count == expected_transitions.count
+      @error             = :found_states
+      @found_states      = expected_transitions - remaining_states
+    end
+
+    @error ? false : true
+  end
+
+
+
+  # The state to be checked.
+  chain :from do |state|
+    @state = state
+  end
+
+
+
+  # The transitions to check
+  chain :to do |*transitions|
+    @to        = transitions.flatten
+    @to_called = true
+  end
+
+
+
+  # Failure messages for an expected match.
+  #
+  failure_message do
+    case @error
+    when :no_state_gates
+      "no state machines are defined for #{@source_name}."
+
+    when :invalid_key
+      "no state machine is defined for ##{@key}."
+
+    when :invalid_state
+      ":#{@state} is not a valid state for #{@source_name}##{@key}."
+
+    when :no_from
+      'missing ".from(<state>)".'
+
+    when :no_to
+      'missing ".to(<states>)".'
+
+    when :invalid_transition_states
+      states = @invalid_states.map { |s| ":#{s}" }
+      if states.one?
+        "#{states.first} is not a valid ##{@key} state."
+      else
+        "#{states.to_sentence} are not valid ##{@key} states."
+      end
+
+    when :missing_states
+      states = @missing_states.map { |s| ":#{s}" }
+      "##{@key} also transitions from :#{@state} to #{states.to_sentence}."
+
+    when :extra_states
+      states = @extra_states.map { |s| ":#{s}" }
+      "##{@key} does not transition from :#{@state} to #{states.to_sentence}."
+    end
+  end
+
+
+
+  # failure messages for a negated match.
+  #
+  failure_message_when_negated do
+    case @error
+    when :no_state_gates
+      "no state machines are defined for #{@source_name}."
+
+    when :invalid_key
+      "no state machine is defined for ##{@key}."
+
+    when :invalid_state
+      ":#{@state} is not a valid state for #{@source_name}##{@key}."
+
+    when :no_from
+      'missing ".from(<state>)".'
+
+    when :no_to
+      'missing ".to(<states>)".'
+
+    when :invalid_transition_states
+      states = @invalid_states.map { |s| ":#{s}" }
+      if states.one?
+        "#{states.first} is not a valid ##{@key} state."
+      else
+        "#{states.to_sentence} are not valid ##{@key} states."
+      end
+
+    when :found_states
+      states = @found_states.map { |s| ":#{s}" }
+      ":#{@state} is allowed to transition to #{states.to_sentence}."
+    end
+  end
+
+
+
+  # = Helpers
+  # ======================================================================
+
+  # Check the setup is correct with the required information available.
+  #
+  def valid_setup?(attr_name, source_obj) # :nodoc:
+    @key            = StateGate.symbolize(attr_name)
+    @state          = StateGate.symbolize(@state)
+    @source_name    = source_obj.is_a?(Class) ? source_obj.name : source_obj.class.name
+
+    # detect_setup_errors(source_obj)
+
+    return false unless assert_state_gate(source_obj)
+    return false unless assert_valid_key(source_obj)
+    return false unless assert_from_present
+    return false unless assert_valid_state
+    return false unless assert_to_present
+
+    assert_valid_transition
+  end
+
+
+
+  # Validate the state machines container exists
+  #
+  def assert_state_gate(source_obj)
+    return true if source_obj.respond_to?(:stateables)
+
+    @error = :no_state_gates
+    false
+  end
+
+
+
+  # Validate the state machine is there
+  #
+  def assert_valid_key(source_obj)
+    @eng = source_obj.stateables[@key]
+    return true unless @eng.blank?
+
+    @error = :invalid_key
+    false
+  end
+
+
+
+  # Validate the :from state is present
+  #
+  def assert_from_present
+    return true unless @state.blank?
+
+    @error = :no_from
+    false
+  end
+
+
+
+  # Validate it is a valid state supplied
+  #
+  def assert_valid_state
+    return true if @eng.states.include?(@state)
+
+    @error = :invalid_state
+    false
+  end
+
+
+
+  # Validate the transitions have been supplied
+  #
+  def assert_to_present
+    return true if @to_called
+
+    @error = :no_to
+    false
+  end
+
+
+
+  # Validate the supplied transitions are valid
+  #
+  def assert_valid_transition
+    return true unless invalid_transition_states?
+
+    @error = :invalid_transition_states
+    false
+  end
+
+
+
+  # Check the supplied transition states are valid for the attribute.
+  #
+  def invalid_transition_states? # :nodoc:
+    @invalid_states = []
+    @to.each do |state|
+      unless @eng.states.include?(state.to_s.to_sym)
+        @invalid_states << state.to_s.to_sym
+        @error = :invalid_transition_states
+      end
+    end
+
+    @invalid_states.any? ? true : false
+  end
+end