darthjee-core_ext 1.7.4 → 2.0.0

data/lib/darthjee/core_ext/hash/deep_hash_constructor.rb

@@ -3,90 +3,154 @@
 module Darthjee
   module CoreExt
     module Hash
+      # @api private
+      #
+      # @author Darthjee
+      #
+      # Class responsible for creating a Hash deep hash
+      #
+      # Deep hash construction happens when a hash of one layer
+      # (no sub hashes) has keys that, once explitted, can be
+      # assembled in a hash with many layers
+      #
+      # @see Transformable#squash
+      # @see Transformable#to_deep_hash
+      #
+      # @example (see Transformable#to_deep_hash)
+      # @example General Usage
+      #   hash = {
+      #     'account.person.name[0]' => 'John',
+      #     'account.person.name[1]' => 'Wick',
+      #     'account.person.age'     =>  20,
+      #     'account.number'         => '102030',
+      #     :'house.number'          => 67,
+      #     :'house.zip'             => 12_345
+      #   }
+      #
+      #   constructor = Darthjee::CoreExt::Hash::DeepHashConstructor.new('.')
+      #
+      #   constructor.deep_hash(hash)  # returns {
+      #                                #   'account' => {
+      #                                #     'person' => {
+      #                                #       'name'   => ['John', 'Wick'],
+      #                                #       'age'    =>  20
+      #                                #     },
+      #                                #     'number' => '102030',
+      #                                #   },
+      #                                #   'house' => {
+      #                                #     'number' => 67,
+      #                                #     'zip'    => 12345
+      #                                #   }
+      #                                # }
       class DeepHashConstructor
-        attr_accessor :separator
+        autoload :Setter, "#{PATH}/hash/deep_hash_constructor/setter"
 
-        def initialize(separator)
+        # @param separator [::String] keys splitter
+        def initialize(separator = '.')
           @separator = separator
         end
 
-        def deep_hash(object)
-          if object.is_a? Array
-            array_deep_hash(object)
-          elsif object.is_a? Hash
-            hash_deep_hash(object)
-          else
-            object
+        # Performs deep hash transformation
+        #
+        # @param hash [::Hash] On layered hash
+        #
+        # @return [::Hash] Many layered hash
+        #
+        # @example (see DeepHashConstructor)
+        def deep_hash(hash)
+          break_keys(hash).tap do
+            hash.each do |key, value|
+              hash[key] = deep_hash_value(value)
+            end
           end
         end
 
         private
 
-        def array_deep_hash(array)
-          array.map do |value|
-            value.is_a?(Hash) ? deep_hash(value) : value
-          end
-        end
-
-        def hash_deep_hash(hash)
-          {}.tap do |new_hash|
-            hash.each do |k, v|
-              base_key, child_key = split_key(k, separator)
-              set_deep_hash_positioned_value(new_hash, base_key, v, child_key)
-            end
+        # @private
+        attr_reader :separator
 
-            new_hash.each do |k, v|
-              new_hash[k] = deep_hash(v)
-            end
+        # @private
+        # break the keys creating sub-hashes
+        #
+        # @param hash [::Hash] hash to be broken
+        #
+        # @example Breaking many level keys
+        #   hash = {
+        #     'account.person.name[0]' => 'John',
+        #     'account.person.name[1]' => 'Wick',
+        #     'account.person.age'     =>  20,
+        #     'account.number'         => '102030',
+        #     :'house.number'          => 67,
+        #     :'house.zip'             => 12_345
+        #   }
+        #
+        #   constructor = Darthjee::CoreExt::Hash::DeepHashConstructor.new('.')
+        #
+        #   constructor.send(:break_keys, hash)
+        #
+        #   # Returns {
+        #   #   'account' => {
+        #   #     %w[person name[0]] => 'John',
+        #   #     %w[person name[1]] => 'Wick',
+        #   #     %w[person age]     =>  20,
+        #   #     %w[number]         => '102030'
+        #   #   },
+        #   #   'house' => {
+        #   #     %w[number] => 67,
+        #   #     %w[zip]    => 12_345
+        #   #   }
+        #   # }
+        #
+        # @return [Hash]
+        def break_keys(hash)
+          hash.keys.each do |key|
+            value = hash.delete(key)
+            base_key, child_key = split_key(key, separator)
+            Setter.new(hash, base_key).set(child_key, value)
           end
-        end
-
-        def split_key(key, separator)
-          separator_rxp = separator == '.' ? "\\#{separator}" : separator
-          skipper = "[^#{separator}]"
-          regexp = Regexp.new("^(#{skipper}*)#{separator_rxp}(.*)")
-          match = key.match(regexp)
 
-          match ? match[1..2] : key
+          hash
         end
 
-        def set_deep_hash_array_value(hash, base_key, index, value, key = nil)
-          key_without_index = base_key.gsub("[#{index}]", '')
-          hash[key_without_index] ||= []
-
-          if key.nil?
-            hash[key_without_index][index] = value
-          else
-            hash[key_without_index][index] ||= {}
-            hash[key_without_index][index][key] = value
-          end
+        # @private
+        #
+        # Recursively proccess a value calling deep hash on it
+        #
+        # @return [::Object]
+        def deep_hash_value(object)
+          return array_deep_hash(object) if object.is_a? Array
+          return deep_hash(object) if object.is_a? Hash
+          object
         end
 
-        def set_deep_hash_positioned_value(new_hash, base_key, value, child_key)
-          index = array_index(base_key)
-
-          if index
-            set_deep_hash_array_value(
-              new_hash, base_key, index,
-              value, child_key
-            )
-          else
-            set_deep_hash_value(new_hash, base_key, value, child_key)
+        # @private
+        #
+        # Map array performing deep hash on its Hash elements
+        #
+        # @param array [::Array] array to be mapped
+        #
+        # @return [::Array]
+        def array_deep_hash(array)
+          array.map do |value|
+            deep_hash_value(value)
           end
         end
 
-        def array_index(key)
-          match = key.match(/\[([^)]+)\]/)
-          match && match[1].to_i
-        end
+        # @private
+        #
+        # Split key into array of keys
+        #
+        # @param key [::String,::Symbol] key to be splitted
+        # @param separator [::String] string of key splitting
+        #
+        # @return [::Array<::String>,::String]
+        def split_key(key, separator)
+          keys = key.is_a?(Array) ? key : key.to_s.split(separator)
 
-        def set_deep_hash_value(hash, base_key, value, key = nil)
-          if key.nil?
-            hash[base_key] = value
-          else
-            hash[base_key] ||= {}
-            hash[base_key][key] = value
-          end
+          return keys unless keys.second
+
+          [keys.shift, keys]
         end
       end
     end

data/lib/darthjee/core_ext/hash/deep_hash_constructor/setter.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Darthjee
+  module CoreExt
+    module Hash
+      class DeepHashConstructor
+        # @api private
+        #
+        # Class responsible for setting value localized inside hash
+        #
+        # @example Simple usage
+        #   hash   = {}
+        #   base   = 'person'
+        #   setter = Darthjee::CoreExt::Hash::DeepHashConstructor::Setter.new(
+        #     hash, base
+        #   )
+        #
+        #   setter.set('age', 21)
+        #
+        #   hash # changed to {
+        #        #   'person' => {
+        #        #     'age' => 21,
+        #        #   }
+        #        # }
+        class Setter
+          # @param hash [Hash] hash to be changed
+          # @param base_key [::String] base key of hash where
+          #   subhash will be created
+          def initialize(hash, base_key)
+            @hash     = hash
+            @base_key = base_key
+          end
+
+          # Sets a value in the correct key inside the hash
+          #
+          # @param key [::String,::NilClass] key where value will live
+          # @param value [::Object] value to be set
+          #
+          # @return [::Object] value
+          #
+          # @example (see DeepHashConstructor)
+          #
+          # @example With Array index
+          #   hash   = {}
+          #   base   = 'person[0]'
+          #   setter = Darthjee::CoreExt::Hash::DeepHashConstructor::Setter.new(
+          #     hash, base
+          #   )
+          #
+          #   setter.set('age', 21)
+          #
+          #   hash # changed to {
+          #        #   'person' => [{
+          #        #     'age' => 21,
+          #        #   }]
+          #        # }
+          def set(key, value)
+            return hash[base_key] = value unless key || index
+            return array[index]   = value unless key
+
+            sub_hash[key] = value
+          end
+
+          private
+
+          # @private
+          attr_reader :hash, :base_key
+
+          # @private
+          # Extract index of array from base_key
+          #
+          # @return [::NilClass,::Integer]
+          def index
+            return @index if instance_variable_defined?('@index')
+
+            match = base_key.match(/\[([^)]+)\]/)
+            return @index = nil unless match
+
+            @index = match[1].to_i
+          end
+
+          # @private
+          # Returns array that will receive value
+          #
+          # This array is only created / used when base_key
+          # contains index
+          #
+          # @return [::Array]
+          def array
+            return @array if instance_variable_defined?('@array')
+
+            key_without_index = base_key.tr("[#{index}]", '')
+
+            @array = hash[key_without_index] ||= []
+          end
+
+          # @private
+          # Returns sub hash that will receive the value
+          #
+          # This sub_hash is only build when key is not nil
+          #
+          # @return [::Hash]
+          def sub_hash
+            return array[index] ||= {} if index
+
+            hash[base_key] ||= {}
+          end
+        end
+      end
+    end
+  end
+end

data/lib/darthjee/core_ext/hash/key_changeable.rb

@@ -7,14 +7,26 @@ module Darthjee
       # changing / transforming keys of a Hash
       #
       # @api public
+      #
+      # @author Darthjee
+      #
+      # @see KeyChanger
+      # @see KeysSorter
       module KeyChangeable
-        # Change all keys by publically sending methods to the keys without
-        # changing the original hash
+        ##########################################
+        # Key change methods
+        ##########################################
+
+        # Change all keys without changing the original hash
+        #
+        # It changes all keysby publically sending methods
+        # to the keys
         #
         # @return [::Hash] New hash with the resulting keys
-        # @param [::Array<Symbol>] calls methods to be called form the key`
+        # @param [::Array<Symbol>] calls methods to be
+        #   called form the key`
         #
-        # @see #change_keys
+        # @see #chain_change_keys!
         #
         # @example
         #   hash = { first: 1, second: 2 }
@@ -24,13 +36,15 @@ module Darthjee
           deep_dup.chain_change_keys!(*calls)
         end
 
-        # Change all keys by publically sending methods to the keys
-        # changing the original hash
+        # Change all keys changing the original hash
+        #
+        # It changes all keys by publically sending methods
+        # to the keys
         #
         # @return [::Hash] New hash with the resulting keys
         # @param [::Array<Symbol>] calls methods to be called form the key`
         #
-        # @see #chain_change_keys
+        # @see #change_keys
         #
         # @example (see #chain_change_keys)
         def chain_change_keys!(*calls)
@@ -45,10 +59,13 @@ module Darthjee
         #
         # @return new Hash with modified keys
         # @param [::Hash] options options to passed to KeyChanger
-        # @option options [Boolean] recursive: flag defining the
+        # @option options [::TrueClass,::FalseClass]
+        #   recursive (true) flag defining the
         #   change to happen also
         #   on inner hashes (defaults to: true)
         #
+        # @yield (key) changing key block
+        #
         # @see Hash::KeyChanger#change_keys
         #
         # @example
@@ -71,10 +88,13 @@ module Darthjee
         #
         # @return self
         # @param [::Hash] options options to passed to KeyChanger
-        # @option options [Boolean] recursive: flag defining the
+        # @option options [::TrueClass,::FalseClass]
+        #   recursive: (true) flag defining the
         #   change to happen also
         #   on inner hashes (defaults to: true)
         #
+        # @yield (key) changing key block
+        #
         # @see Hash::KeyChanger#change_keys
         #
         # @example (see #change_keys)
@@ -83,58 +103,93 @@ module Darthjee
         end
 
         # prepend a string to all keys
-        # options {
-        #  recursive: true,
-        #  type: :keep [keep, string, symbol] (key type to be returned)
-        # }
-        # ex: { :a => 1, "b"=> 2 }.prepend_to_keys("foo_")
-        # # returns { :foo_a => 1, "foo_b"=> 2 }
+        #
+        # @param options [::Hash]
+        # @option options [::TrueClass,::FalseClass]
+        #   recursive (true)
+        #   flag indicating transformation should be recursive
+        # @option options [::Symbol] type (:keep)
+        #   type of the final key
+        #   - keep : cast the result to the same type of the
+        #     original key
+        #   - string : cast the result to be {::String}
+        #   - symbol cast the result to be {::Symbol}
+        #
+        # @return [::Hash]
+        #
+        # @see KeyChanger#change_keys
+        #
+        # @example
+        #   hash = { :a => 1, "b"=> 2 }
+        #
+        #   hash.prepend_to_keys("foo_") # returns {
+        #                                #   :foo_a => 1,
+        #                                #   "foo_b"=> 2
+        #                                # }
         def prepend_to_keys(str, options = {})
           change_key_text(options) do |key|
             "#{str}#{key}"
           end
         end
 
-        # append a string to all keys
-        # options {
-        #  recursive: true,
-        #  type: :keep [keep, string, symbol] (key type to be returned)
-        # }
-        # ex: { :a => 1, "b"=> 2 }.append_to_keys("_bar")
-        # # returns { :a_bar => 1, "b_bar"=> 2 }
+        # Append a string to all keys
+        #
+        # @param options [::Hash]
+        # @option options [::TrueClass,::FalseClass]
+        #   recursive (true)
+        #   flag indicating transformation should be recursive
+        # @option options [::Symbol] type (:keep)
+        #   type of the final key
+        #   - keep : cast the result to the same type of the
+        #     original key
+        #   - string : cast the result to be {::String}
+        #   - symbol cast the result to be {::Symbol}
+        #
+        # @return [::Hash]
+        #
+        # @see KeyChanger#change_keys
+        #
+        # @example (see #prepend_to_keys)
         def append_to_keys(str, options = {})
           change_key_text(options) do |key|
             "#{key}#{str}"
           end
         end
 
-        # sorts keys for hash
-        # options: { recursive: true }
-        # ex: { b:1, a:2 }.sort_keys == { a:2, b:1 }
-        def sort_keys(options = {})
+        # Sorts keys for hash changing the original
+        #
+        # @param options [::Hash]
+        # @option options [::TrueClass,::FalseClass]
+        #   recursive (true) flag indicating recursive sorting
+        #
+        # @return [::Hash]
+        #
+        # @see KeySorter#sort
+        #
+        # @example
+        #   hash = { b: 1, a: 2 }
+        #
+        #   hash.sort_keys  # changes hash to { a: 2, b: 1 }
+        def sort_keys!(options = {})
           Hash::KeysSorter.new(self, **options).sort
         end
 
-        ##########################################
-        # Value change methods
-        ##########################################
-
-        # creates a new hash with changes in its values
-        # options: {
-        #   recursive: true,
-        #   skip_hash:true
-        # }
-        # ex: { a:1, b:2 }.change_values{ |v| v+1 } == { a:2, b:3 }
-        # ex: { a:1, b:{ c:1 } }.change_values(skip_hash:false) { |v| v.to_s }
-        # # returns { a:"1", b:"{ c=>1 }
-        # ex: { a:1, b:{ c:1 } }.change_values(skip_hash:true) { |v| v.to_s }
-        # # returns { a:"1", b:{ c=>"1" } }
-        def change_values(options = {}, &block)
-          deep_dup.change_values!(options, &block)
-        end
-
-        def change_values!(options = {}, &block)
-          Hash::ValueChanger.new(options, &block).change(self)
+        # Sorts keys for hash without changing the original
+        #
+        # @param options [::Hash]
+        # @option options [::TrueClass,::FalseClass]
+        #   recursive (true) flag indicating recursive sorting
+        #
+        # @return [::Hash]
+        #
+        # @see KeySorter#sort
+        #
+        # @example
+        #   hash = { b: 1, a: 2 }
+        #
+        #   hash.sort_keys  # returns { a: 2, b: 1 }
+        def sort_keys(options = {})
+          Hash::KeysSorter.new(deep_dup, **options).sort
         end
 
         # Changes the key of the hash without changing it
@@ -143,7 +198,10 @@ module Darthjee
         #
         # @example
         #   hash = { a: 1, b: 2 }
-        #   hash.remap_keys(a: :b, b: :c) # returns { b: 1, c: 2 }
+        #   hash.remap_keys(a: :b, b: :c) # returns {
+        #                                 #   b: 1,
+        #                                 #   c: 2
+        #                                 # }
         def remap_keys(remap)
           dup.remap_keys!(remap)
         end
@@ -159,13 +217,27 @@ module Darthjee
 
         private
 
-        # changes the text of the keys
-        # options {
-        #  recursive: true,
-        #  type: :keep [keep, string, symbol] (key type to be returned)
-        # }
-        # ex: { :a => 1, "b"=> 2 }.change_key_text{ |key| key.upcase }
-        # # returns { :A => 1, "B"=> 2 }
+        # @private
+        # @api private
+        #
+        # Changes the text of the keys
+        #
+        # @param options [::Hash]
+        # @option options [::TrueClass,::FalseClass]
+        #   recursive (true)
+        #   flag indicating transformation should be recursive
+        # @option options [::Symbol] type (:keep)
+        #   type of the final key
+        #   - keep : cast the result to the same type of the
+        #     original key
+        #   - string : cast the result to be {::String}
+        #   - symbol cast the result to be {::Symbol}
+        #
+        # @yield (key) changing key block
+        #
+        # @return [::Hash]
+        #
+        # @see KeyChanger
         def change_key_text(options = {}, &block)
           Hash::KeyChanger.new(self).change_text(options, &block)
         end