state_gate 1.2.3

data/lib/state_gate/rspec/have_states.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+##
+# = Description
+#
+# RSpec matcher to verify defined states.
+#
+# [:source_obj]
+#   The Class or Instance to be tested.
+#
+# [:for]
+#   The attrbute being tested.
+#
+# [:states]
+#   The expected states as Symbols or Strings
+#
+#  expect(User).to have_states(:pending, :active).for(:status)
+#
+# Fails if an exisiting state is missing or there are defined states that
+# have not been included.
+#
+RSpec::Matchers.define :have_states do |*states| # rubocop:disable Metrics/BlockLength
+  #
+  # Expect the given states to match all the states for the attribute.
+  #
+  match do |source_obj| # :nodoc:
+    # validate we have a state engine and parameters
+    return false unless valid_setup?(states, source_obj)
+
+    @missing_states = @eng.states - @states
+    @extra_states   = @states     - @eng.states
+
+    @error = :missing_states if @missing_states.any?
+    @error = :extra_states   if @extra_states.any?
+
+    @error ? false : true
+  end
+
+
+  # Expect the attribute not to have any given states.
+  #
+  match_when_negated do |source_obj|
+    # validate we have a state engine and parameters
+    return false unless valid_setup?(states, source_obj)
+
+    @valid_states = @states.select { |s| @eng.states.include?(s) }
+    @error        = :valid_states_found if @valid_states.any?
+
+    @error ? false : true
+  end
+
+
+  # The attribute that should have the expected states.
+  #
+  chain :for do |attr_name|
+    @key = StateGate.symbolize(attr_name)
+  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 :missing_key
+      'missing ".for(<attribute>)".'
+
+    when :invalid_key
+      "no state machine is defined for ##{@key}."
+
+    when :missing_states
+      states = @missing_states.map { |s| ":#{s}" }
+      if states.one?
+        "#{states.first} is also a valid state for ##{@key}."
+      else
+        "#{states.to_sentence} are also valid states for ##{@key}."
+      end
+
+    when :extra_states
+      states = @extra_states.map { |s| ":#{s}" }
+      if states.one?
+        "#{states.first} is not a valid state for ##{@key}."
+      else
+        "#{states.to_sentence} are not valid states for ##{@key}."
+      end
+    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 :missing_key
+      'missing ".for(<attribute>)".'
+
+    when :invalid_key
+      "no state machine is defined for ##{@key}."
+
+    when :valid_states_found
+      states = @valid_states.map { |s| ":#{s}" }
+      if states.one?
+        "#{states.first} is a valid state for ##{@key}."
+      else
+        "#{states.to_sentence} are valid states for ##{@key}."
+      end
+    end
+  end
+
+
+
+  #  Helpers
+  # ======================================================================
+
+  # Check the setup is correct with the required information available.
+  #
+  def valid_setup?(states, source_obj) # :nodoc:
+    @states         = states.flatten.map { |s| StateGate.symbolize(s) }
+    @source_name    = source_obj.is_a?(Class) ? source_obj.name : source_obj.class.name
+
+    if @key.blank?
+      @error = :missing_key
+
+    elsif !source_obj.respond_to?(:stateables)
+      @error = :no_state_gates
+
+    elsif (@eng = source_obj.stateables[@key]).blank?
+      @error = :invalid_key
+    end
+
+    @error ? false : true
+  end
+end

data/lib/state_gate/rspec.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# relative-require all rspec files
+Dir[File.dirname(__FILE__) + '/rspec/*.rb'].each do |file|
+  require_relative 'rspec/' + File.basename(file, File.extname(file))
+end

data/lib/state_gate/type.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module StateGate
+  ##
+  # = Description
+  #
+  # ActiveRecord::Type to cast a model attribute as a StateGate,
+  # mapping to a string database column.
+  #
+  # Ensures that any string written to, or read from, the database is a valid +state+,
+  # otherwise it raises an exception.
+  #
+  # This class is has an internal API for ActiveRecord and is not intended for public use.
+  #
+  class Type < ::ActiveModel::Type::String
+
+    ##
+    # ensure the value is a legitimate state and return a downcased string
+    #
+    def cast(value) # :nodoc:
+      assert_valid_value(value)
+      value.to_s.downcase.remove(/^force_/)
+    end
+
+
+
+    ##
+    # Return TRUE if the value is serializable, otherwise FASLE.
+    #
+    # a value is serializable if it can be coerced to a String
+    #
+    def serializable?(value) # :nodoc:
+      value.to_s
+    rescue NoMethodError
+      false
+    end
+
+
+
+    ##
+    # Return a downcased String of the given value, providing it is a legitimate state.
+    #
+    def serialize(value) # :nodoc:
+      assert_valid_value(value)
+      value.to_s.downcase.remove(/^force_/)
+    end
+
+
+
+    ##
+    # Raise an exception unless the value is both serializable and a legitimate state
+    #
+    def assert_valid_value(value) # :nodoc:
+      return if serializable?(value) && states.include?(value.to_s.downcase.remove(/^force_/))
+
+      case value
+      when NilClass
+        fail ArgumentError, "'nil' is not a valid state for #{@klass}##{@name}."
+      when Symbol
+        fail ArgumentError, ":#{value} is not a valid state for #{@klass}##{@name}."
+      else
+        fail ArgumentError, "'#{value&.to_s}' is not a valid state for #{@klass}##{@name}."
+      end
+    end
+
+
+
+    ##
+    # Returns TRUE if the other class is equal, otherewise FALSE.
+    #
+    # Equality matches on Class, name and states(in the given order)
+    #
+    def ==(other) # :nodoc:
+      return false unless self.class == other.class
+      return false unless klass      == other.send(:klass)
+      return false unless name       == other.send(:name)
+      return false unless states     == other.send(:states)
+
+      true
+    end
+    alias eql? ==
+
+
+
+    ##
+    # Returns a unique hash value
+    #
+    def hash # :nodoc:
+      [self.class, klass, name, states].hash
+    end
+
+
+
+    # ======================================================================
+    # = Private
+    # ======================================================================
+    private
+
+    attr_reader :klass, :name, :states
+
+
+
+    # initialize and set the class variables
+    #
+    def initialize(klass, name, states) # :nodoc:
+      @klass  = klass
+      @name   = name
+      @states = states.map(&:to_s)
+    end
+
+  end # class Type
+end # StateGate

data/lib/state_gate.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+require_relative  'state_gate/builder'
+
+
+I18n.load_path << File.expand_path('state_gate/locale/engine_en.yml', __dir__)
+I18n.load_path << File.expand_path('state_gate/locale/builder_en.yml', __dir__)
+I18n.load_path << File.expand_path('state_gate/locale/state_gate_en.yml', __dir__)
+
+
+##
+# = StateGate
+#
+# Builds and attaches a _StateGate::Engine_  to the desired ActiveRecord String
+# attribute.
+#
+# *States* and *transitions* are provided within a configuration block, enabling
+# the _state_gate_ to ensure that only defined *states* are accepted as values
+# for the attribute, and that *states* may only transition to allowed *states*.
+#
+#   Class User
+#     include StateGate
+#
+#     state_gate :attribute_name do
+#       ... configuration ...
+#     end
+#   end
+#
+#
+# == Attribute Name
+#
+# The +attribute_name+ *must* be:
+# * a Symbol
+# * the name of a database String column attribute
+# * not an aliased attribute name
+#
+#
+# == Configuration Options
+#
+# 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 StateGate
+
+  ##
+  # Configuration Error for reporting issues with the configuration when
+  # building a new state machine
+  class ConfigurationError < StandardError # :nodoc:
+  end
+
+  ##
+  # Conflict Error for reporting when a generated method name
+  # conflicts with an existing method name
+  class ConflictError < StandardError # :nodoc:
+  end
+
+
+  # ======================================================================
+  #   Model Public Singleton Methods
+  # ======================================================================
+
+  ##
+  # Returns the Symbol version of the provided value as long as it responds to
+  # +#to_s+ and has no included whitespace in the resulting String.
+  #
+  # Returns +nil+ if the coversion fails.
+  #
+  #   StateGate.symbolize('Test')    #=> :test
+  #
+  #   StateGate.symbolize(:Test)     #=> :test
+  #
+  #   StateGate.symbolize('My Test') #=> nil
+  #
+  #   StateGate.symbolize('')        #=> nil
+  #
+  def self.symbolize(val)
+    return nil if     val.blank?
+    return nil unless val.respond_to?(:to_s)
+    return nil unless val.to_s.remove(/\s+/) == val.to_s
+
+    val.to_s.downcase.to_sym
+  end
+
+
+
+  # ======================================================================
+  #   Module Private Singleton methods
+  # ======================================================================
+
+  class << self
+
+
+    #   Private
+    # ======================================================================
+    private
+
+
+
+    # When StateGate is included within a Class, check ActiveRecord is
+    # an ancestor and add the 'state_gate' method to the includeing Class
+    #
+    def included(base) #:nodoc:
+      ar_included = base.ancestors.include?(::ActiveRecord::Base)
+      fail I18n.t('state_gate.included_err', base: base.name) unless ar_included
+
+      generate_state_gate_method_for(base)
+    end
+    private_class_method :included
+
+
+
+    # Raise an exception when StateGate is 'extend' by another Class, to let
+    # the user know that it should be 'included'.
+    #
+    def extended(base) #:nodoc:
+      fail I18n.t('state_gate.extended_err', base: base.name)
+    end
+
+
+
+    # Calls an instance of StateGate::Builder to generate the
+    # 'state_gate' for the Klass attribute.
+    #
+    def generate_state_gate_method_for(klass)
+      klass.define_singleton_method(:state_gate) do |attr_name = nil, &block|
+        # Note: the builder does all it's work on initialize, so nothing more
+        # to do here.
+        StateGate::Builder.new(self, attr_name, &block)
+      end
+    end
+
+  end # class << self
+
+end # module StateGate

metadata

@@ -0,0 +1,83 @@
+--- !ruby/object:Gem::Specification
+name: state_gate
+version: !ruby/object:Gem::Version
+  version: 1.2.3
+platform: ruby
+authors:
+- CodeMeister
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2021-11-26 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 5.0.0.beta1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 5.0.0.beta1
+description: "     State management for ActiveRecord, with states; transitions; and
+  \    just the right amount of syntactic sugar.   "
+email: state_gate@codemeister.dev
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/state_gate.rb
+- lib/state_gate/builder.rb
+- lib/state_gate/builder/conflict_detection_methods.rb
+- lib/state_gate/builder/dynamic_module_creation_methods.rb
+- lib/state_gate/builder/scope_methods.rb
+- lib/state_gate/builder/state_methods.rb
+- lib/state_gate/builder/transition_methods.rb
+- lib/state_gate/builder/transition_validation_methods.rb
+- lib/state_gate/engine.rb
+- lib/state_gate/engine/configurator.rb
+- lib/state_gate/engine/errator.rb
+- lib/state_gate/engine/fixer.rb
+- lib/state_gate/engine/scoper.rb
+- lib/state_gate/engine/sequencer.rb
+- lib/state_gate/engine/stator.rb
+- lib/state_gate/engine/transitioner.rb
+- lib/state_gate/locale/builder_en.yml
+- lib/state_gate/locale/engine_en.yml
+- lib/state_gate/locale/state_gate_en.yml
+- lib/state_gate/rspec.rb
+- lib/state_gate/rspec/allow_transitions_on.rb
+- lib/state_gate/rspec/have_states.rb
+- lib/state_gate/type.rb
+homepage: https://github.com/Rubology/state_gate
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/Rubology/state_gate
+  source_code_uri: https://github.com/Rubology/state_gate
+  changelog_uri: https://github.com/Rubology/state_gate/blob/master/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.5'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.2.32
+signing_key:
+specification_version: 4
+summary: State management for ActiveRecord.
+test_files: []