state_gate 1.2.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1a3a28a8136472a91cd7c75616e189dd2c92a7b57a0bc18645395a46c55ff906
+  data.tar.gz: c909cd3d3a1101056ff1fe33ea6b94e38008f26a093476d7aaeb4ac17847b1ad
+SHA512:
+  metadata.gz: 6b9cae6865505456fafa9da807e8472eb148f8af294c7631690b28ebba7b01c20e93f27b2bbe3ccf16c7ec27ea872e604726323bebb7639c7e7db726eb4bdd34
+  data.tar.gz: 7c104de800820cedee61c177a44504e2e1f052aaf529fd4990d3407ae337a4004c925f12162762f2db66b34a96ecda327e06e0c96c4dfc299feef63885b0e6f6

data/lib/state_gate/builder/conflict_detection_methods.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module StateGate
+  class Builder
+    ##
+    # = Description
+    #
+    # Multiple private methods providing error handling functionality for
+    # StateGate::Builder.
+    #
+    module ConflictDetectionMethods
+
+      #  Private
+      # ======================================================================
+      private
+
+      # Check if a class method is already defined. Checks are made:
+      # 1 --> is it an ActiveRecord dangerous method?
+      # 2 --> is it an ActiveRecord defined class method?
+      # 3 --> is it a singleton method of the klass?
+      # 4 --> is it defined within any of the klass ancestors?
+      #
+      # If found, raise an error giving a guide to where the method has been defined
+      #
+      def detect_class_method_conflict!(method_name)
+        defining_klass = _active_record_protected_method?(method_name) ||
+                         _klass_singleton_method?(method_name) ||
+                         _klass_ancestor_singleton_method?(method_name)
+
+        return unless defining_klass
+
+        raise_conflict_error method_name, type: 'a class', source: defining_klass
+      end
+
+
+
+      # Check an instance method is already defined. Checks are made:
+      # 1 --> is it an ActiveRecord dangerous method?
+      # 2 --> is it an ActiveRecord defined instance method?
+      # 3 --> is it an instance method of the klass?
+      # 4 --> is it defined within any of the klass ancestors?
+      #
+      # If found, raise an error giving a guide to where the method has been defined
+      #
+      def detect_instance_method_conflict!(method_name)
+        defining_klass = _active_record_protected_method?(method_name) ||
+                         _klass_instance_method?(method_name) ||
+                         _klass_ancestor_instance_method?(method_name)
+
+        return unless defining_klass
+
+        raise_conflict_error method_name, source: defining_klass
+      end
+
+
+
+      # Raise a StateGate::ConflictError with a details message of the problem
+      #
+      # = Message
+      #
+      #           StateGate for Klass#attribute will generate a class
+      #           method 'statuses', which is already defined by ActiveRecord.
+      #
+      def raise_conflict_error(method_name, type: 'an instance', source: 'ActiveRecord')
+        fail StateGate::ConflictError, I18n.t('state_gate.builder.conflict_err',
+                                              klass:       @klass,
+                                              attribute:   @attribute,
+                                              type:        type,
+                                              method_name: method_name,
+                                              source:      source)
+      end
+
+
+
+      # Check if the method is an ActiveRecord dangerous method name
+      #
+      def _active_record_protected_method?(method_name) #:nodoc:
+        'ActiveRecord' if _dangerous_method_names.include?(method_name)
+      end
+
+
+
+      # Check if the method is a singleton method of the klass
+      #
+      def _klass_singleton_method?(method_name) #:nodoc:
+        @klass.name if @klass.singleton_methods(false).include?(method_name.to_sym)
+      end
+
+
+
+      # Check if the method is an ancestral singleton method of the klass
+      #
+      def _klass_ancestor_singleton_method?(method_name) #:nodoc:
+        return nil unless @klass.respond_to?(method_name)
+
+        @klass.singleton_class
+              .ancestors
+              .select { |a| a.instance_methods(false).include?(method_name.to_sym) }
+              .first
+      end
+
+
+
+      # Check if the method an instance method of the klass
+      #
+      def _klass_instance_method?(method_name) #:nodoc:
+        @klass.instance_methods(false).include?(method_name.to_sym) ? @klass.name : nil
+      end
+
+
+
+      # Check if the method is an ancestral singleton method of the klass
+      #
+      def _klass_ancestor_instance_method?(method_name) #:nodoc:
+        return nil unless @klass.instance_methods.include?(method_name.to_sym)
+
+        @klass.ancestors
+              .select { |a| a.instance_methods(false).include?(method_name.to_sym) }
+              .first
+      end
+
+
+
+      # returns an array of dagerous methods names found in
+      # ActiveRecord::AttributeMethods::RESTRICTED_CLASS_METHODS (which is called
+      # BLACKLISTED_CLASS_METHODS in 5.0 and 5.1)
+      #
+      def _dangerous_method_names
+        %w[private public protected allocate new name parent superclass]
+      end
+
+    end # ConflictDetectionMethods
+  end # Builder
+end # StateGate

data/lib/state_gate/builder/dynamic_module_creation_methods.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module StateGate
+  class Builder
+    ##
+    # = Description
+    #
+    # Multiple private methods enabling StateGate::Builder to dynamically
+    # generate module, instance and class helper methods.
+    #
+    module DynamicModuleCreationMethods
+
+      #  Private
+      # ======================================================================
+      private
+
+
+
+      # = Dynamic Module Creation
+      # ======================================================================
+
+      # Dynamically generated module to hold the StateGate helper methods. This
+      # keeps a clear distinction between the state machine helper methods and the klass'
+      # own methods.
+      #
+      # The module is named after the class and is created if needed, or reused if exisitng.
+      #
+      # Note:
+      #       the module is named "<klass>::StateGate_HelperMethods"
+      #
+      def _helper_methods_module
+        @_helper_methods_module ||= begin
+          if @klass.const_defined?('StateGate_HelperMethods')
+            "#{@klass}::StateGate_HelperMethods".constantize
+          else
+            @klass.const_set('StateGate_HelperMethods', Module.new)
+            mod = "#{@klass}::StateGate_HelperMethods".constantize
+            @klass.include mod
+            mod
+          end
+        end
+      end
+
+
+      #   Method Re-defined Detection
+      # ======================================================================
+
+
+      # Adds the hook method :method_added to the Klass, detecting any new method
+      # definitions for an attribute already defined as a StateGate.
+      #
+      # If a matching method is discoverd, it adds a warning to logger, if defined,
+      # otherwise it outputs the warning to STDOUT via `puts`
+      #
+      # method_name - the name of the newly defined method.
+      #
+      # Note
+      #
+      # This method is added last so it does not trigger when StateGate adds
+      # the attribute methods.
+      #
+      #  meta
+      #
+      # * loop though each state machine attribute.
+      #   * does the new defined method use 'attr' or 'attr='?
+      #     * if so then record an error logger if denied, othewise use `puts`
+      #
+      def _generate_method_redefine_detection # rubocop:disable Metrics/MethodLength
+        @klass.instance_eval(%(
+          def method_added(method_name)
+            stateables.keys.each do |attr_name|
+              if method_name&.to_s == attr_name ||
+                 method_name&.to_s == "\#{attr_name}="
+
+                msg  = "WARNING! \#{self.name}#\#{attr_name} is a defined StateGate and"
+                msg += " redefining :\#{method_name} may cause conflict."
+
+                logger ? logger.warn(msg) : puts("\n\n\#{msg}\n\n")
+              end
+
+              super(method_name)
+            end
+          end
+        ), __FILE__, __LINE__ - 15)
+      end
+
+
+
+      #   Method Creation
+      # ======================================================================
+
+      # Add an Class helper method to the _helper_methods_module
+      #
+      # method_name - a String name for the method, needed to check for conflicts
+      # file        - a String file name for error reporting
+      # line        - a String or Integer line number for error reporting
+      # method_body - a String to bhe evaluates in the module
+      #
+      def add__klass__helper_method(method_name, file, line, method_body)
+        detect_class_method_conflict!(method_name)
+        @klass.instance_eval(method_body, file, line)
+      end
+
+
+
+      # Add an instance helper method to the _helper_methods_module
+      #
+      # method_name - a String name for the method, needed to check for conflicts
+      # file        - a String file name for error reporting
+      # line        - a String or Integer line number for error reporting
+      # method_body - a String to bhe evaluates in the module
+      #
+      def add__instance__helper_method(method_name, file, line, method_body)
+        detect_instance_method_conflict!(method_name)
+        _helper_methods_module.module_eval(method_body, file, line)
+      end
+
+    end # DynamicModuleCreationMethods
+  end # Builder
+end # StateGate

data/lib/state_gate/builder/scope_methods.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module StateGate
+  class Builder
+    ##
+    # = Description
+    #
+    # Multiple private methods enabling StateGate::Builder to generate
+    # scopes for each state.
+    #
+    # * fetch all records with the given state:
+    #     Klass.active # => Klass.where(state: :active)
+    #
+    # * fetch all records without the given state:
+    #     Klass.not_active # => Klass.where.not(state: :active)
+    #
+    # * fetch all records with the supplied states:
+    #     Klass.with_statuses(:pending, :active) # => Klass.where(state: [:pending, :active])
+    #
+    module ScopeMethods
+
+      # = Private
+      # ======================================================================
+      private
+
+
+      # Add scopes to the klass for filtering by state
+      #
+      # Note:
+      #       The scope name is a concatenation of <prefix><state name><suffix>
+      #
+      def generate_scope_methods
+        return unless @engine.include_scopes?
+
+        _add__klass__state_scopes
+        _add__klass__not_state_scopes
+        _add__klass__with_attrs_scope
+
+        _add__klass__with_attrs_scope(@alias) if @alias
+      end
+
+
+
+      # ======================================================================
+      #  Klass methods
+      # ======================================================================
+
+      # Add a klass method that scopes records to the specified state.
+      #   eg:
+      #       Klass.active         # => ActiveRecord::Relation
+      #       Klass.active_status  # => ActiveRecord::Relation
+      #
+      def _add__klass__state_scopes
+        attr_name = @attribute
+
+        @engine.states.each do |state|
+          scope_name = @engine.scope_name_for_state(state)
+          detect_class_method_conflict! scope_name
+          @klass.scope(scope_name, -> { where(attr_name => state) })
+        end # each state
+      end # _add__klass__state_scopes
+
+
+
+      # Add a klass method that scopes records to those without the specified state.
+      #   eg:
+      #       Klass.not_active         # => ActiveRecord::Relation
+      #       Klass.not_active_status  # => ActiveRecord::Relation
+      #
+      def _add__klass__not_state_scopes
+        attr_name = @attribute
+
+        @engine.states.each do |state|
+          scope_name = @engine.scope_name_for_state(state)
+          detect_class_method_conflict! "not_#{scope_name}"
+          @klass.scope "not_#{scope_name}", -> { where.not(attr_name => state) }
+        end # each state
+      end # _add__klass__not_state_scopes
+
+
+
+      # Add a klass method that scopes records to the given states.
+      #   eg:
+      #       Klass.with_statuses(:active, :pending) # => ActiveRecord::Relation
+      #
+      def _add__klass__with_attrs_scope(method_name = @attribute)
+        attr_name   = @attribute
+        method_name = "with_#{method_name.to_s.pluralize}"
+
+        detect_class_method_conflict! method_name
+        @klass.scope method_name, ->(states) { where(attr_name => Array(states)) }
+      end # _add__klass__with_attrs_scope
+
+    end # LockingMethods
+  end # Builder
+end # StateGate

data/lib/state_gate/builder/state_methods.rb

@@ -0,0 +1,289 @@
+# frozen_string_literal: true
+
+module StateGate
+  class Builder
+    ##
+    # = Description
+    #
+    # Multiple private methods enabling StateGate::Builder to generate
+    # state functionality.
+    #
+    # * query the class for all state:
+    #     Klass.statuses  # => [:pending, :active, :archived]
+    #
+    # * query the class for the human names of all state:
+    #     Klass.human_statuses  # => ['Pending Activation', 'Active', 'Archived']
+    #
+    # * query the class for an Array of human names/state names for use in a select form:
+    #     Klass.statuses_for_select
+    #     # => [['Pending Activation', 'pending'],["Active', 'active'], ['Archived','archived']]
+    #
+    # * list all attribute states:
+    #     .status_states  # => [:pending, :active, :archived]
+    #
+    # * list all human names for the attribute states:
+    #     .status_human_names  # => ['Pending Activation', 'Active', 'Archived']
+    #
+    # * list the human name for the attribute state:
+    #     .human_status  # => 'Pending Activation'
+    #
+    # * is a particular state set:
+    #     .pending?   # => false
+    #     .active?    # => true
+    #     .archived?  # => false
+    #
+    # * is a particular state not set:
+    #     .not_pending?   # => true
+    #     .not_active?    # => false
+    #     .not_archived?  # => true
+    #
+    # * list the allowed transitions for the current state.
+    #     .status_transitions  # => [:suspended, :archived]
+    #
+    module StateMethods
+
+      #  Private
+      # ======================================================================
+      private
+
+      # Add Class and instance methods that allow querying states
+      #
+      def generate_state_methods
+        add_state_attribute_methods
+        add_state_alias_methods
+      end
+
+
+
+      # add attribute methods
+      #
+      def add_state_attribute_methods
+        _add__klass__attrs
+        _add__klass__human_attrs
+        _add__klass__attrs_for_select
+
+        _add__instance__attrs
+        _add__instance__human_attrs
+        _add__instance__human_attr        
+        _add__instance__state?
+        _add__instance__not_state?
+        _add__instance__attrs_for_select
+      end
+
+
+
+      # add alias methods
+      #
+      def add_state_alias_methods
+        return unless @alias
+
+        _add__klass__attrs(@alias)
+        _add__klass__human_attrs(@alias)
+        _add__klass__attrs_for_select(@alias)
+
+        _add__instance__attrs(@alias)
+        _add__instance__human_attrs(@alias)
+        _add__instance__attrs_for_select(@alias)
+      end
+
+
+
+      # ======================================================================
+      #  Class Merthods
+      # ======================================================================
+
+      # Adds a Class method to return an Array of the defined states for the attribute
+      #   eg:
+      #       Klass.statuses   # => [:pending, :active, :suspended, :archived]
+      #
+      def _add__klass__attrs(method_name = @attribute)
+        method_name = method_name.to_s.pluralize
+
+        add__klass__helper_method(method_name, __FILE__, __LINE__ - 2, %(
+          def #{method_name}
+            stateables[:#{@attribute}].states
+          end
+        ))
+      end
+
+
+
+      # Adds a Class method to return an Array of the human names of the defined states
+      # for the attribute
+      #   eg:
+      #       Klass.human_statuses   # => ['Pending Activation', 'Active',
+      #                                    'Suspended by Admin', 'Archived']
+      #
+      def _add__klass__human_attrs(method_name = @attribute)
+        method_name = "human_#{method_name.to_s.pluralize}"
+
+        add__klass__helper_method(method_name, __FILE__, __LINE__ - 2, %(
+          def #{method_name}
+            stateables[:#{@attribute}].human_states
+          end
+        ))
+      end
+
+
+
+      # Adds a Class method to return an Array of the human and state names for the
+      # attribute, suitable for using in a form select statement.
+      #
+      # sorted - if TRUE, the array is sorted in alphabetical order by human name
+      #          otherwise it is in the order specified
+      #
+      #   Klass.statuses_for_select         # => [ ['Pending Activation', 'pending'],
+      #                                            ['Active', 'active'],
+      #                                            ['Suspended by Admin', 'suspended',
+      #                                            ['Archived', 'archived'] ]
+      #
+      #   Klass.statuses_for_select(true)   # => [ ['Active', 'active'],
+      #                                            ['Pending Activation', 'pending'],
+      #                                            ['Suspended by Admin', 'suspended',
+      #                                            ['Archived', 'archived'] ]
+      #
+      # Note:
+      #       States should NEVER be set from direct user selection. This method is
+      #       intended for use within search forms, where the user may filter by state.
+      #
+      def _add__klass__attrs_for_select(method_name = @attribute)
+        method_name = "#{method_name.to_s.pluralize}_for_select"
+
+        add__klass__helper_method(method_name, __FILE__, __LINE__ - 2, %(
+          def #{method_name}(sorted = false)
+            stateables[:#{@attribute}].states_for_select(sorted)
+          end
+        ))
+      end
+
+
+
+      # ======================================================================
+      #  Instance Methods
+      # ======================================================================
+
+      # Adds an Instance method to return Array of the defined states for the attribute
+      #   eg:
+      #       .statuses   # => [:pending, :active, :suspended, :archived]
+      #
+      def _add__instance__attrs(method_name = @attribute)
+        method_name = method_name.to_s.pluralize
+
+        add__instance__helper_method(method_name, __FILE__, __LINE__ - 2, %(
+          def #{method_name}
+            stateables[:#{@attribute}].states
+          end
+        ))
+      end
+
+
+
+      # Adds an Instance method to return an Array of the human names for the attribute
+      #   eg:
+      #       .status_human_states   # => ['Pending Activation', 'Active',
+      #                                    'Suspended by Admin', 'Archived']
+      #
+      def _add__instance__human_attrs(method_name = @attribute)
+        method_name = "human_#{method_name.to_s.pluralize}"
+
+        add__instance__helper_method(method_name, __FILE__, __LINE__ - 2, %(
+          def #{method_name}
+            stateables[:#{@attribute}].human_states
+          end
+        ))
+      end
+
+
+
+      # Adds an Instance method to return the human name for the attribute's state
+      #   eg:
+      #       .human_status   # => 'Suspended by Admin'
+      #
+      def _add__instance__human_attr(method_name = @attribute)
+        method_name = "human_#{method_name.to_s}"
+
+        add__instance__helper_method(method_name, __FILE__, __LINE__ - 2, %(
+          def #{method_name}
+            stateables[:#{@attribute}].human_state_for(#{@attribute})
+          end
+        ))
+      end
+
+
+
+      # Adds an Instance method for each state, returning TRUE if the state is set
+      #   eg:
+      #     --> when :active
+      #       .active?     # => true
+      #       .archived?   # => false
+      #
+      def _add__instance__state?
+        @engine.states.each do |state|
+          method_name = "#{@engine.scope_name_for_state(state)}?"
+
+          add__instance__helper_method(method_name, __FILE__, __LINE__ - 3, %(
+            def #{method_name}
+              self[:#{@attribute}] == :#{state}.to_s
+            end
+          ))
+        end
+      end
+
+
+
+      # Adds an Instance method for each state, returning TRUE if the state is not set.
+      #   eg:
+      #     --> when :active
+      #       .not_active?     # => false
+      #       .not_archived?   # => true
+      #
+      # def _add__instance__not_state?
+      #   attr_name = @attribute
+      #
+      def _add__instance__not_state?
+        @engine.states.each do |state|
+          method_name = "not_#{@engine.scope_name_for_state(state)}?"
+
+          add__instance__helper_method(method_name, __FILE__, __LINE__ - 3, %(
+            def #{method_name}
+              self[:#{@attribute}] != :#{state}.to_s
+            end
+          ))
+        end
+      end
+
+
+
+      # Adds a, Instance method to return an Array of the human and state names for the
+      # attribute, suitable for using in a form select statement.
+      #
+      # sorted - if TRUE, the array is sorted in alphabetical order by human name
+      #          otherwise it is in the order specified
+      #
+      #   .statuses_for_select         # => [ ['Pending Activation', 'pending'],
+      #                                       ['Active', 'active'],
+      #                                       ['Suspended by Admin', 'suspended',
+      #                                       ['Archived', 'archived'] ]
+      #
+      #   .statuses_for_select(true)   # => [ ['Active', 'active'],
+      #                                       ['Pending Activation', 'pending'],
+      #                                       ['Suspended by Admin', 'suspended',
+      #                                       ['Archived', 'archived'] ]
+      #
+      # Note:
+      #       States should NEVER be set from direct user selection. This method is
+      #       intended for use within search forms, where the user may filter by state.
+      #
+      def _add__instance__attrs_for_select(method_name = @attribute)
+        method_name = "#{method_name.to_s.pluralize}_for_select"
+
+        add__instance__helper_method(method_name, __FILE__, __LINE__ - 2, %(
+          def #{method_name}(sorted = false)
+            stateables[:#{@attribute}].states_for_select(sorted)
+         end
+        ))
+      end
+
+    end # StateMethods
+  end # Builder
+end # StateGate