state_gate 1.2.3 → 1.3.0

data/lib/state_gate/engine/configurator.rb

@@ -12,61 +12,61 @@ module StateGate
     #
     # 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]
+    #   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]
+    #   **_: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]
+    #   **_: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]
+    #   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
+    # [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
+    # [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]
+    #   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
+    #   **_: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
+    #   **_: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]
+    #   Optional setting to disable the generation of Class Scope helpers methods.
     #     no_scopes
     #
     module Configurator
@@ -81,53 +81,61 @@ module StateGate
       # ======================================================================
 
 
+      ##
       # Execute the provided configuration.
       #
+      # @block config
+      #   the given configuration
+      #
       # ==== actions
       #
-      #   + create sequence links and transitions
-      #   + create scope names
-      #   + remove duplicate transitions for each state
+      # - 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
+      # - 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)
+      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
+        _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.
       #
+      # @block config
+      #   the given configuration
+      #
       # ==== actions
       #
-      #   + create sequence links and transitions
-      #   + create scope names
-      #   + remove duplicate transitions for each state
+      # - 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
+      # - 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)
+      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
+        _cerr :bad_command, cmd: err_command
       end
 
 
@@ -136,21 +144,22 @@ module StateGate
       #  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
+      def _assert_states_are_valid
         state_names = @states.keys
 
         # are there states
-        cerr(:states_missing_err) if state_names.blank?
+        _cerr(:states_missing_err) if state_names.blank?
 
         # is there more than one state
-        cerr(:single_state_err) if state_names.one?
+        _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)
+          _cerr(:default_state_err) unless state_names.include?(@default)
         else
           @default = state_names.first
         end
@@ -158,11 +167,12 @@ module StateGate
 
 
 
+      ##
       # 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
+      def _assert_transitions_exist
         return if @states.map { |_state, opts| opts[:transitions_to] }.uniq.flatten.any?
 
         @transitionless = true
@@ -173,39 +183,42 @@ module StateGate
 
 
 
+      ##
       # Ensure that there is only one of reach transition
       #
-      def assert_uniq_transitions
+      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
+      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)
+            _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
+      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)
+              _cerr(:transition_state_err, state: state_name, transition: transition, kattr: true)
             end
           end
         end
@@ -213,16 +226,17 @@ module StateGate
 
 
 
+      ##
       # Ensure there is a transition leading to every non-default state.
       #
-      def assert_all_states_are_reachable
+      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)
+        _cerr(:transitionless_states_err, states: states, kattr: true)
       end
 
     end # ConfigurationMethods

data/lib/state_gate/engine/errator.rb

@@ -6,8 +6,8 @@ module StateGate
     # = 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
+    # - all error messages are I18n configured
+    # - method names are deliberately short to encourage code readability with
     #   if/unless one-liners
     module Errator
 
@@ -15,24 +15,39 @@ module StateGate
       # ======================================================================
       private
 
+      ##
       # Format the given value and report an ArgumentError
       #
-      def invalid_state_error(val)
+      # @param [String]
+      #   the error message
+      #
+      # @raise [ArgumentError]
+      #
+      def _invalid_state_error(val)
         case val
         when NilClass
-          aerr :invalid_state_err, val: "'nil'", kattr: true
+          _aerr :invalid_state_err, val: "'nil'", kattr: true
         when Symbol
-          aerr :invalid_state_err, val: ":#{val}", kattr: true
+          _aerr :invalid_state_err, val: ":#{val}", kattr: true
         else
-          aerr :invalid_state_err, val: "'#{val&.to_s}'", kattr: true
+          _aerr :invalid_state_err, val: "'#{val&.to_s}'", kattr: true
         end
       end
 
 
 
+      ##
       # Report a ConfigurationError, including the Klass#attr variable.
       #
-      def cerr(err, **args)
+      # @param [Symbol] err
+      #   the I18n error message key
+      #
+      # @param [Hash] args
+      #   arguments to be included in the error
+      #
+      # @raise [ConfigurationError]
+      #
+      def _cerr(err, **args)
         args[:kattr] = "#{@klass}##{@attribute}" if args[:kattr] == true
         key          = "state_gate.engine.config.#{err}"
         fail ConfigurationError, I18n.t(key, **args)
@@ -40,9 +55,18 @@ module StateGate
 
 
 
+      ##
       # Report a RuntimeError, including the Klass#attr variable.
       #
-      def rerr(err, **args)
+      # @param [Symbol] err
+      #   the I18n error message key
+      #
+      # @param [Hash] args
+      #   arguments to be included in the error
+      #
+      # @raise [RuntimeError]
+      #
+      def _rerr(err, **args)
         args[:kattr] = "#{@klass}##{@attribute}" if args[:kattr] == true
         key          = "state_gate.engine.#{err}"
         fail I18n.t(key, **args)
@@ -50,9 +74,18 @@ module StateGate
 
 
 
+      ##
       # Report an ArgumentError, including the Klass#attr variable.
       #
-      def aerr(err, **args)
+      # @param [Symbol] err
+      #   the I18n error message key
+      #
+      # @param [Hash] args
+      #   arguments to be included in the error
+      #
+      # @raise [ArgumentError]
+      #
+      def _aerr(err, **args)
         args[:kattr] = "#{@klass}##{@attribute}" if args[:kattr] == true
         key          = "state_gate.engine.#{err}"
         fail ArgumentError, I18n.t(key, **args)

data/lib/state_gate/engine/fixer.rb

@@ -13,15 +13,19 @@ module StateGate
       #   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
+      # @param [Symbol] val
+      #   the prefix to use
+      #
+      # @example
+      #   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
+        _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
 
@@ -29,13 +33,16 @@ module StateGate
 
       # 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
+      # @param [Symbol] val
+      #   the suffix to use
+      #
+      # @example
+      #   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
+        _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
 
@@ -49,8 +56,9 @@ module StateGate
       # Returns the defined prefix for the state_gate, or an empty string if no
       # prefix has been defined.
       #
-      #   .state_prefix   # => 'my_prefix'
-      #   .state_prefix   # => ''
+      # @example
+      #   .state_prefix   #=> 'my_prefix'
+      #   .state_prefix   #=> ''
       #
       def state_prefix
         @prefix
@@ -62,8 +70,9 @@ module StateGate
       # Returns the defined suffix for the state_gate, or an empty string if no
       # suffix has been defined.
       #
-      #   .state_suffix   # => 'my_suffix'
-      #   .state_suffix   # => ''
+      # @example
+      #   .state_suffix   #=> 'my_suffix'
+      #   .state_suffix   #=> ''
       #
       def state_suffix
         @suffix

data/lib/state_gate/engine/scoper.rb

@@ -13,8 +13,10 @@ module StateGate
       #   Configuration Methods
       # ======================================================================
 
+      ##
       # Disables the generation of Class Scope helpers methods
       #
+      # @example
       #   no_scopes
       #
       def no_scopes
@@ -23,6 +25,7 @@ module StateGate
 
 
 
+      ##
       # Generate the scope name to use for each state.
       #
       def generate_scope_names
@@ -40,7 +43,8 @@ module StateGate
       ##
       # Returns TRUE if scope methods should be added to the model, otherwise FALSE.
       #
-      #   .include_scopes?  # => true
+      # @example
+      #   .include_scopes?  #=> true
       #
       def include_scopes?
         !!@scopes
@@ -52,9 +56,13 @@ module StateGate
       # 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'
+      # @param [Symbol] state_name
+      #   the state to generate the scope_name for
+      #
+      # Example
+      #   .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)

data/lib/state_gate/engine/sequencer.rb

@@ -15,16 +15,23 @@ module StateGate
       #   Configuration Methods
       # ======================================================================
 
+      ##
       # Automatically add transitions from each state to the preceeding and following states.
       #   make_sequential
       #
-      # [:one_way]
+      # @param [Array[Symbol]] args
+      #   the optional configuration arguments
+      #
+      # @option args [Symbol] :one_way
       #   Only adds tranitions from each state to the follow state. (optional)
-      #     make_sequential :one_way
       #
-      # [:loop]
+      # @option args [Symbol] :loop
       #   Adds transitions from the last state to the first and from the first to the last
       #   (unless also :one_way) (optional)
+      #
+      # @example
+      #     make_sequential :one_way
+      #     make_sequential :loop
       #     make_sequential :one_way, :loop
       #
       def make_sequential(*args)
@@ -35,6 +42,7 @@ module StateGate
 
 
 
+      ##
       # Add sequence hooks if sequential requested.
       #
       def generate_sequences
@@ -47,6 +55,7 @@ module StateGate
 
 
 
+      ##
       # Add the previous sequential state
       #
       def add_previous_sequential_state
@@ -64,6 +73,7 @@ module StateGate
 
 
 
+      ##
       # Add the next sequential state
       #
       def add_next_sequential_state
@@ -79,6 +89,7 @@ module StateGate
 
 
 
+      ##
       # Add the first and last transitions to complete the sequential loop.
       #
       def loop_sequence
@@ -103,9 +114,11 @@ module StateGate
       # ======================================================================
 
       ##
-      # return TRUE if the state_gate is sequential, otherwise FALSE.
+      # @return [Boolean]
+      #  true if the state_gate is sequential, otherwise false.
       #
-      #   .sequential?  # => TRUE
+      # @example
+      #   .sequential?  #=> TRUE
       #
       def sequential?
         !!@sequential