state_gate 1.2.3 → 1.3.0

data/lib/state_gate/engine/stator.rb

@@ -15,27 +15,28 @@ module StateGate
 
       # Add a new +state+.
       #
-      # [:state_name*]
-      #   The name for the new state. (Symbol | required)
+      # @param [Symbol, String] name
+      #   The name for the new state. It must be converatbel to a Symbol
       #     state :state_name
       #
+      # @param [Hash] opts
+      #   configuration options for the given state
       #
-      # [:transitions_to]
+      # @option opts [Hash] :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)
+      # @option opts [Hash] :human
+      #   A display name for the state used in views, defaulting to 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)
+        _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 })
+        @states[name] = _state_template.merge({ human: opts[:human] || name.to_s.titleize })
 
         # add the state transitions
         Array(opts[:transitions_to]).each do |transition|
@@ -45,14 +46,19 @@ module StateGate
 
 
 
+      ##
       # The name for the default state for a new object. (String | required)
       #
+      # @param [Symbol] default_state
+      #   the state name to set as default
+      #
+      # @example
       #   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)
+      def default(default_state = nil)
+        _cerr(:default_type_err, kattr: true) unless default_state.is_a?(Symbol)
+        _cerr(:default_repeat_err, kattr: true) if   @default
+        @default = StateGate.symbolize(default_state)
       end
 
 
@@ -64,7 +70,8 @@ module StateGate
       ##
       # Returns an Array defined states.
       #
-      #   .states  # => [:pending, :active, :suspended, :archived]
+      # @example
+      #   .states  #=> [:pending, :active, :suspended, :archived]
       #
       def states
         @states.keys
@@ -75,26 +82,30 @@ module StateGate
       ##
       # Ensures the given value is a valid state name.
       #
-      # [value]
-      #   A String or Symbol state name.
+      # @param [String, Symbol] value
+      #   the state name.
       #
-      #     .assert_valid_state!(:active)    # => :active
-      #     .assert_valid_state!('PENDING')  # => :pending
-      #     .assert_valid_state!(:dummy)     # => ArgumentError
+      # @example
+      #   .assert_valid_state!(:active)    #=> :active
+      #   .assert_valid_state!('PENDING')  #=> :pending
+      #   .assert_valid_state!(:dummy)     #=> ArgumentError
       #
       #
-      # [Note]
+      # @note
       #   Valid state names preceeded with +force_+ are also allowed.
       #
-      #     .assert_valid_state!(:force_active)  # => :force_active
+      #     .assert_valid_state!(:force_active)  #=> :force_active
       #
-      # Returns the Symbol state name
-      # Raises an exception if the value is not a valid state name.
+      # @return [Symbol]
+      #   the Symbol state name
+      #
+      # @raise [ArgumentError]
+      #   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)
+        _invalid_state_error(value) unless @states.keys.include?(unforced_state)
         state_name
       end
 
@@ -103,7 +114,8 @@ module StateGate
       ##
       # Returns an Array of the human display names for each defined state.
       #
-      #   human_states  # => ['Pending Activation', 'Active', 'Suspended By Admin']
+      # @example
+      #   human_states  #=> ['Pending Activation', 'Active', 'Suspended By Admin']
       #
       def human_states
         @states.map { |_k, v| v[:human] }
@@ -114,8 +126,12 @@ module StateGate
       ##
       # Returns the human display name for a given state.
       #
-      #   .human_state_for(:pending)  # => 'Panding Activation'
-      #   .human_state_for(:active)   # => 'Active'
+      # @param [Symbol] state
+      #   the state name
+      #
+      # @example
+      #   .human_state_for(:pending)  #=> 'Panding Activation'
+      #   .human_state_for(:active)   #=> 'Active'
       #
       def human_state_for(state)
         state_name = assert_valid_state!(state)
@@ -128,15 +144,20 @@ module StateGate
       # 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
+      # @param [Boolean] 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']]
+      # @return [Array[Array[Strings]]]
+      #   Array of state names with their human names
       #
-      #   .states_for_select(true)  # => [['Active', 'active'],
-      #                             #     ['Pending Activation', 'pending'],
-      #                             #     ['Suspended by Admin', 'suspended']]
+      # @example
+      #   .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 = []
@@ -152,12 +173,14 @@ module StateGate
 
 
       ##
-      # Return the raw states hash, allowing inspection of the core engine states.
+      # @return [Hash]
+      #   a hash of states and their transitions & human names
       #
-      #   .raw_states  # => { pending: { transitions_to: [:active],
-      #                #                 human:          'Pending Activation'},
-      #                #      active:  { transitions_to: [:pending],
-      #                #                 human:          'Active'}}
+      # @example
+      #   .raw_states  #=> { pending: { transitions_to: [:active],
+      #                                  human:          'Pending Activation'},
+      #                       active:  { transitions_to: [:pending],
+      #                                  human:          'Active'}}
       #
       def raw_states
         @states
@@ -166,9 +189,11 @@ module StateGate
 
 
       ##
-      # Returns the state_gate default state
+      # @return [String]
+      #   the state_gate default state
       #
-      #   .default_state   # => :pending
+      # @example
+      #   .default_state   #=> :pending
       #
       def default_state
         @default
@@ -183,8 +208,11 @@ module StateGate
 
 
 
-      # return a Hash with the state keys defined.
-      def state_template
+      ##
+      # @return [Hash]
+      #   of the state keys defined.
+      #
+      def _state_template
         {
           transitions_to: [],
           previous_state: nil,
@@ -196,28 +224,45 @@ module StateGate
 
 
 
-      # fail if the supplied name is not a symbol, already added
+      ##
+      # Raises an error 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_')
+      # @param [Symbol] name
+      #   the state name to validate
+      #
+      # @raise [AygumentError]
+      #   if the state name is invalid
+      #
+      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.
+      ##
+      # raises an error if opts is not a hash, has non-symbol keys or non-symbol transitions.
+      #
+      # @param [Hash] opts
+      #   an options hash
+      #
+      # @param [Symbol] name
+      #   the state name
+      #
+      # @raise [ArgumentError]
+      #   if any invalid options
       #
-      def assert_valid_opts(opts, state_name)
+      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)
+          _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)
+        _cerr(:transition_key_type_err, state: state_name, kattr: true)
       end
 
     end # Stater

data/lib/state_gate/engine/transitioner.rb

@@ -10,10 +10,12 @@ module StateGate
     module Transitioner
 
       ##
-      # Returns TRUE if every state can transition to every other state, rendering
-      # transitions pointless.
+      # @return [Boolean]
+      #   true if every state can transition to every other state, rendering
+      #   transitions pointless.
       #
-      #   .transitionless?  # => true
+      # @example
+      #   .transitionless?  #=> true
       #
       def transitionless?
         !!@transitionless
@@ -22,12 +24,14 @@ module StateGate
 
 
       ##
-      # Returns a Hash of states and allowed transitions.
+      # @return [Hash]
+      #   of states and allowed transitions.
       #
-      #   .transitions  # => { pending:   [:active],
-      #                 #      ativive:   [:suspended, :archived],
-      #                 #      suspended: [:active, :archived],
-      #                 #      archived:  [] }
+      # @example
+      #   .transitions  #=> { pending:   [:active],
+      #                        ativive:   [:suspended, :archived],
+      #                        suspended: [:active, :archived],
+      #                        archived:  [] }
       #
       def transitions
         @transitions ||= begin
@@ -40,9 +44,14 @@ module StateGate
 
 
       ##
-      # Return an Array of allowed transitions for the given state
+      # @param [Symbol, String] state
+      #   the state name
       #
-      #   .transitions_for_state(:active) # => [:suspended, :archived]
+      # @return [Array]
+      #   of allowed transitions for the given state
+      #
+      # @example
+      #   .transitions_for_state(:active) #=> [:suspended, :archived]
       #
       def transitions_for_state(state)
         state_name = assert_valid_state!(state)
@@ -52,10 +61,15 @@ module StateGate
 
 
       ##
-      # Returns TRUE if a transition is allowed, otherwise raises an exception.
+      # @return [true]
+      #   if a transition is allowed
+      #
+      # @raise [ArgumentError]
+      #   if a transition is invalid
       #
-      #   .assert_valid_transition!(:pending, :active) # => true
-      #   .assert_valid_transition!(:active, :pending) # => ArgumentError
+      # @example
+      #   .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)
@@ -65,7 +79,7 @@ module StateGate
         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)
+        _aerr(:invalid_state_transition_err, from: from_state, to: to_state, kattr: true)
       end
 
     end # Sequencer

data/lib/state_gate/engine.rb

@@ -28,30 +28,43 @@ module StateGate
     # ======================================================================
     private
 
+    ##
     # Initialize the engine, setting the Class and attribute for the new engine
     # and parsing the provided configuration.
     #
+    # @param [Class] klass
+    #   The class containing the attribute to be cast as a state gate
+    #
+    # @param [Symbol] attribute
+    #   The name of the database attribute to use for the state gate
+    #
+    # @block config
+    #   The configuration block for the state gate.
+    #
+    # @example
     #   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?
+      _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
+      _set_defaults
 
-      parse_configuration(&config)
+      _parse_configuration(&config)
     end
 
 
 
+    ##
     # Set the class variables with default values
-    def set_defaults
+    #
+    def _set_defaults
       @states         = {}
       @default        = nil
       @prefix         = nil

data/lib/state_gate/type.rb

@@ -12,6 +12,8 @@ module StateGate
   #
   # This class is has an internal API for ActiveRecord and is not intended for public use.
   #
+  # @private
+  #
   class Type < ::ActiveModel::Type::String
 
     ##
@@ -19,7 +21,7 @@ module StateGate
     #
     def cast(value) # :nodoc:
       assert_valid_value(value)
-      value.to_s.downcase.remove(/^force_/)
+      cast_value(value)
     end
 
 
@@ -47,6 +49,17 @@ module StateGate
 
 
 
+    ##
+    # Convert a nil DB value to the default state.
+    #
+    def deserialize(value) # :nodoc:
+      return value if value
+
+      klass.constantize.stateables[name].default_state
+    end
+
+
+
     ##
     # Raise an exception unless the value is both serializable and a legitimate state
     #
@@ -99,7 +112,7 @@ module StateGate
     attr_reader :klass, :name, :states
 
 
-
+    ##
     # initialize and set the class variables
     #
     def initialize(klass, name, states) # :nodoc:
@@ -108,5 +121,12 @@ module StateGate
       @states = states.map(&:to_s)
     end
 
+
+    ##
+    # convert the value to lowercase and remove and 'force_' prefix
+    #
+    def cast_value(value)
+      value.to_s.downcase.remove(/^force_/)
+    end
   end # class Type
 end # StateGate